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Abstract 


The  benefits  of  programming  in  a  functional  style  are  well  known.  In  par¬ 
ticular,  algorithms  that  are  expressed  as  compositions  of  functions  operating 
on  series/ vectors  streams  of  data  elements  are  much  easier  to  understand  and 
modify  than  equivalent  algorithms  expressed  as  loops.  Unfortunately,  many 
programmers  hesitate  to  use  series  expressions,  because  they  are  typically 
implemented  very  inefficiently. 

A  Common  Lisp  macro  package  (OSS)  has  been  implemented  which  sup¬ 
ports  a  restricted  class  of  series  expressions,  obviously  synchronizable  series 
expressions,  which  can  be  evaluated  very  efficiently  by  automatically  convert¬ 
ing  them  into  loops.  Using  this  macro  package,  programmers  can  obtain  the 
advantages  of  expressing  computations  as  series  expressions  without  incurring 
any  run-time  overhead. 
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The  benefits  of  programming  in  a  functional  style  are  well  known.  In 
particular,  algorithms  that  are  expressed  as  compositions  of  functions  oper¬ 
ating  on  series/vectors/streams  of  data  elements  are  much  easier  to  under¬ 
stand  and  modify  than  equivalent  algorithms  expressed  as  loops.  Unfortunately 
many  programmers  hesitate  to  use  series  expressions,  because  they  are  typicall 
implemented  very  inefficiently. 

A  Common  Lisp  macro  package  (OSS)  has  been  implemented  which  supports  a 
restricted  class  of  series  expression,  obviously  synchronizable  (Block  20  Cont 
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series  expressions,  which  can  be  evaluated  very  efficiently  by  automatically 
converting  them  into  loops.  Using  this  macro  package,  programmers  can  obtain 
the  advantages  of  expressing  computations  as  series  without  incurring  any 
run-time  overhead. 
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1.  All  You  Need  To  Know  to  Get  Started 


l  his  first  section  describes  everything  you  need  to  know  to  start  using  the  OSS  macro 
package.  It  then  presents  a  detailed  example.  Section  2  is  a  comprehensive  reference  man¬ 
ual.  It  describes  the  functions  supported  by  the  OSS  macro  package  in  detail.  Section  3 
contains  the  bibliography.  Section  4  explains  the  error  messages  that  can  be  produced 
by  the  OSS  macro  package.  Section  5  is  both  an  index  into  Section  2  and  an  abbreviated 
description  of  the  OSS  functions. 

A  companion  paper  6  gives  an  overview  of  the  theory  underlying  the  OSS  macro 
package.  It  explains  why  things  are  designed  the  way  they  are  and  compares  the  OSS 
macro  package  with  other  systems  that  support  operations  on  series.  In  addition,  the 
companion  paper  gives  a  brief  description  of  the  algorithms  used  to  implement  the  OSS 
macro  package.  As  part  of  this,  it  describes  a  number  of  subprimitive  constructs  which 
are  provided  for  advanced  users  of  the  OSS  macro  package. 

The  OSS  data  type.  A  series  is  an  ordered  linear  sequence  of  elements.  Vectors, 
lists,  and  streams  are  examples  of  series  data  types.  The  advantages  (with  respect  to  con¬ 
ciseness,  understandability.  and  modifiability)  of  expressing  algorithms  as  compositions 
of  functions  operating  on  series,  rather  than  as  loops,  are  well  known.  Unfortunately, 
as  typically  implemented,  series  expressions  are  very  inefficient  -so  inefficient,  that  pro¬ 
grammers  are  forced  to  use  loops  whenever  efficiency  matters. 

Obviously  Synchronizable  Series  (OSS)  is  a  special  series  data  type  that  can  be  im¬ 
plemented  extremely  efficiently  by  automatically  converting  OSS  expressions  into  loops. 
This  allows  programmers  to  gain  the  benefit  of  using  series  expressions  without  paying 
any  price  in  efficiency. 

The  OSS  macro  package  adds  support  for  the  OSS  data  type  to  Common  I.isp  4;.  The 
macro  package  was  originally  developed  under  version  7  of  the  Symbolics  Lisp  Machine 
software  [7  .  However,  it  is  written  in  standard  Common  Lisp  and  should  be  able  to  run 
in  any  implementation  of  Common  Lisp.  (It  has  been  tested  in  DEC  Common  Lisp  and 
Sun  Common  Lisp  as  well  as  Symbolics  Common  Lisp.) 

The  basic  functionality  provided  by  the  OSS  macro  package  is  similar  to  the  function¬ 
ality  provided  by  the  Common  Lisp  sequence  functions.  However,  in  addition  to  being 
much  more  efficient,  the  OSS  macro  package  is  more  powerful  than  the  sequence  func¬ 
tions,  because  it  includes  almost  all  of  the  operations  supported  by  APL  [3:  and  by  the 
Loop  macro  i 2] .  As  a  result.  OSS  expressions  go  much  farther  than  the  sequence  functions 
towards  the  goal  of  eliminating  the  need  for  explicit  loops. 

Predefined  OSS  functions.  The  heart  of  the  OSS  macro  package  is  a  set  of  several 
dozen  functions  which  operate  on  OSS  series.  These  functions  divide  naturally  into  three 
classes.  Enumerators  produce  OSS  series  without  consuming  any.  Transducers  compute 
OSS  series  from  OSS  series.  Reducers  consume  OSS  series  without  producing  any.  As  a 
mnemonic  device,  the  name  of  each  predefined  OSS  function  begins  with  a  letter  code 
that  indicates  the  type  of  operation.  These  letters  are  intended  to  be  pronounced  as 
separate  syllables. 

Predefined  enumerators  include  Elist  which  enumerates  successive  elements  of  a  list, 
Evector  which  enumerates  the  elements  of  a  vector,  and  Eup  which  enumerates  the  inte- 
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gers  in  a  range.  (In  the  examples  below,  the  notation  [...]  is  used  to  represent  an  oss 
series. ) 


(Elist  ’(a  b  c))  =>  [a  b  c] 

(Evector  #(a  be))  =>  [a  b  c] 

(Eup  1  :to  3)  =>  [123] 

Predefined  transducers  include  Tpositions  which  returns  the  positions  of  the  non-null 
elements  in  a  series  and  Tselect  which  selects  the  elements  of  its  second  argument  which 
correspond  to  non-null  elements  of  its  first  argument. 

(Tpositions  [a  nil  b  c  nil  nil])  =>  [023] 

(Tselect  [nil  T  T  nil]  [l  2  3  4] )  =>  [2  3] 

Predefined  reducers  include  Rlist  which  combines  the  elements  of  a  series  into  a  list. 
Rsum  which  adds  up  the  elements  of  a  series.  Rlength  which  computes  the  length  of  a 
series,  and  Rfirst  which  returns  the  first  element  of  a  series. 

(Rlist  [a  b  c] )  =>  (a  b  c) 

(Rsum  [1  2  3])  =>  6 
(Rlength  [a  b  c] )  =>  3 
(Rfirst  [a  b  c] )  =>  a 

As  simple  illustrations  of  how  OSS  functions  are  used,  consider  the  following. 

(Rsum  (Evector  #(1  2  3)))  =>  6 

(Rlist  (Tpositions  (Elist  ’(a  nil  b  c  nil))))  =>(023) 


Higher-Order  OSS  functions.  The  OSS  macro  package  provides  a  number  of 
higher-order  functions  which  support  general  classes  of  oss  operations.  ( Kach  of  these 
functions  end  in  the  suffix  "F'\  which  is  pronounced  separately.) 

For  example,  enumeration  is  supported  by  (EnumerateF  init  step  test).  This  enumer¬ 
ates  an  OSS  series  of  elements  starting  with  init  by  repeatedly  applying  step.  The  OSS 
series  consists  of  the  values  up  to.  but  not  including,  the  first  value  for  which  test  is  true. 

Reduction  is  supported  by  (ReduceF  init  function  items)  which  is  analogous  to  the 
sequence  function  reduce.  The  elements  of  the  OSS  series  items  are  combined  together 
using  function.  The  quantity  init  is  used  as  an  initial  seed  value  for  the  accumulation. 

Mapping  is  supported  by  (TmapF  function  items)  which  is  analogous  to  the  sequence 
function  map.  An  OSS  series  is  computed  by  applying  function  to  each  element  of  the  OSS 
series  items. 

(EnumerateF  3  #’l-  t’minusp)  =>  [3210] 

(ReduceF  0  •’+  [123])  =>  6 
(TmapF  #’sqrt  [4  9  16] )  =>  [2  3  4] 


Implicit  mapping.  1  he  oss  macro  package  contain'  a  special  mechanism  that 
makes  mapping  particularly  easy.  W  henever  an  ordinary  Lisp  function  is  applied  to  an 
oss  series,  it  is  automatically  mapped  over  the  elements  of  the  oss  series.  For  example, 
iri  the  expression  below,  the  function  sqrt  is  mapped  over  the  oss  series  of  numbers 
created  bv  Evector. 
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(Rsum  (sqrt  (Evector  #(4  16)))) 

=  (Rsum  (TmapF  #’sqrt  (Evector  #(4  16))))  6 

lo  a  considerable  extent.  implicit  mapping  is  a  peripheral  part  of  the  oss  macro 
package  one  can  always  use  TmapF  instead.  However,  due  to  the  ubiquitous  nature  of 
mapping,  implicit  mapping  i>  extremely  convenient.  As  illustrated  belo\  ,  its  key  virtue 
is  that  it  reduces  the  number  of  literal  lambda  expressions  that  have  to  be  written. 

(Rsum  (expt  (abs  (Evector  #(2  -2  3)))  3)) 

IE  (Rsum  (TmapF  #’(lambda  (x)  (expt  (abs  x)  3)) 

(Evector  #(2  -2  3))))  43 

Creating  OSS  variables.  The  OSS  macro  package  provides  two  forms  (lets  and 
lets*  I  which  are  analogous  to  let  and  let*,  except  that  they  make  it  possible  to  c  reate 
variables  that  can  hold  OSS  series.  (The  suffix  ‘‘S'.  pronounced  separately,  is  used  to 
indicate  primitive  OSS  forms.)  As  shown  in  the  example  below,  lets  can  be  used  to  bind 
both  ordinary  variables  (e.g.  n)  and  OSS  variables  (e  g  ,  items). 

(defun  average  (v) 

(lets*  ((items  (Evector  v)) 

(sum  (Rsum  items)) 

(n  (Rlength  items))) 

(/  sum  n) ) ) 

(average  #(1  2  3))  =>  2 

User-defined  OSS  functions.  Sew  OSS  functions  can  be  defined  by  using  the  form 
defunS  which  is  analogous  to  defun.  Explicit  declarations  are  required  inside  defunS  to 
indicate  which  arguments  receive  oss  series.  The  following  example  shows  the  definition 
of  an  OSS  function  which  computes  the  product  of  the  numbers  in  an  OSS  series. 

(defunS  Rproduct  (numbers) 

(declare  (type  oss  numbers)) 

(ReduceF  1  #'*  numbers)) 

(Rproduct  [2  4  6]  )  =>  48 

Restrictions  on  OSS  expressions.  As  illustrated  by  the  examples  above.  OSS 
expressions  are  constructed  in  the  same  way  as  any  other  Lisp  expression — i.e.,  OSS 
functions  are  composed  together  in  any  way  desired.  However,  in  order  to  guarantee  that 
OSS  expressions  can  always  be  converted  into  highly  efficient  loops,  a  few  restrictions 
have  to  be  followed.  These  restrictions  are  summarized  in  the  beginning  of  Section  2  and 
discussed  in  detail  in  (i  .  Here,  it  is  sufficient  to  note  that  these  restrictions  are  checked 
by  the  OSS  macro  package  and  error  u usages  are  issued  whenever  they  are  violated. 

The  best  approach  for  programmers  to  take  is  to  simply  write  OSS  expressions  without 
worrying  about  these  restrictions  and  then  fix  the  expressions  in  the  event  that  the 
restrictions  are  violated,  f n  conjunction  with  the  descriptions  of  the  error  messages 
involved.  Section  1  contains  explicit  suggestions  on  how  to  fix  erroneous  OSS  expressions. 
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Further,  it  should  be  noted  that  simple  oss  expression*  are  very  unlikely  to  violate 
any  of  the  restrictions.  In  particular,  it  is  impossible  for  an  oss  expression  to  violate  any 
of  the  restrictions  unless  it  contains  a  variable  bound  by  lets  or  defunS. 

Benefits.  The  benefit  of  OSS  expressions  is  that  they  retain  most  of  the  advantages 
of  functional  programming  using  series,  while  eliminating  the  costs.  However,  given  the 
restrictions  alluded  to  above,  the  question  naturally  arises  as  to  whether  OSS  expressions 
are  applicable  in  a  wide  enough  range  of  situations  to  be  of  real  pragmatic  benefit. 

An  informal  study  i5  was  undertaken  of  the  kinds  of  loops  programmers  actually 
write.  This  study  suggests  that  approximately  SO1.'  of  the  loops  programmers  write  are 
constructed  by  combining  a  few  common  kinds  of  looping  algorithms.  The  OSS  macro 
package  is  designed  so  that  all  of  these  algorithms  can  be  represented  as  OsS  function*. 
As  a  result,  it  appears  that  approximately  80' 'i  of  loops  can  be  trivially  rewritten  as  OSS 
expressions.  Many  more  can  be  converted  to  this  form  with  only  minor  modification. 

M  oreover.  the  benefits  of  using  OSS  expressions  go  beyond  replacing  individual  loops. 
A  major  shift  toward  using  OSS  expressions  would  be  a  significant  change  in  the  way 
programming  is  done.  At  the  current  time,  most  programs  contain  one  or  more  loops 
and  most  of  the  interesting  computation  in  these  program*  occurs  in  these  loops.  This 
is  quite  unfortunate,  since  loops  are  generally  acknowledged  to  be  one  of  the  hardest 
things  to  understand  in  any  program.  If  OSS  expressions  were  used  whenever  possible, 
most  programs  would  not  contain  any  loops.  This  would  be  a  major  step  forward  in 
conciseness,  readability,  verifiability,  and  maintainability. 

Example 

The  following  example  shows  what  it  is  like  to  use  oss  expressions  in  a  realistic 
programming  context.  The  example  consists  of  two  parts:  a  pair  of  functions  which 
convert  between  sets  represented  as  lists  and  sets  represented  as  bits  packed  into  an 
integer  and  a  graph  algorithm  which  uses  the  integer  representation  of  sets. 

Bit  sets.  Small  sets  can  be  represented  very  efficiently  as  binary  integers  where  each 
l  bit  in  the  integer  represents  an  element  in  the  set.  Below,  sets  represented  in  this 
fashion  are  referred  to  as  bit  sets. 

Common  Lisp  provides  a  number  of  bitwise  operations  on  integers  which  can  be  used 
to  manipulate  bit  sets.  In  particular,  logior  computes  'he  union  of  two  bit  sets  while 
logand  computes  their  intersection. 

The  functions  in  Figure  1.1  convert  between  sets  represented  as  lists  and  bit  sets.  In 
order  to  perform  this  conversion  a  mapping  has  to  be  established  between  bit  positions 
and  potential  set  elements.  This  mapping  is  specified  by  a  universe.  A  universe  is  a  list 
of  elements.  If  a  bit  set  b  is  associated  with  a  universe  u.  then  the  ith  element  in  u  is  in 
the  set  represented  by  b  iff  the  ith  bit  in  b  is  !. 

For  example,  given  the  universe  (abed  e).  the  integer  ftbOlOll  represent*  the  *ot 
la,b,d}.  I  Bv  Common  Lisp  convention,  the  (J t It  bit  in  an  integer  is  the  rightmost  bit.) 

Given  a  bit  set  and  its  associated  universe,  the  function  bs»t->list  convert*  the 
bit  set  into  a  set  represented  as  a  list  of  its  element'.  It  (toe*  this  by  enumerating  the 
'dements  in  the  universe  along  with  their  positions  and  constructing  a  list  of  the  elements 
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(defun  bset->list  (bset  universe) 

(Rlist  (Tselect  (logbitp  fEup  0)  bset)  (Elist  universe)))) 

(defun  list->bset  (list  universe) 

(ReduceF  0  O’logior  (ash  1  (bit-position  (Elist  list)  universe)))) 

(defun  bit-position  (item  universe) 

,or  (Rfirst  (Tpositions  (eq  item  (Elist  universe)))) 

(l-  (length  (nconc  universe  (list  item)))))) 

Figure  l.L:  Converting  between  lists  and  bit  sets. 

which  correspond  to  Is  in  the  integer  representing  the  bit  set.  (When  no  :tc  argument 
is  supplied.  Eup  counts  up  forever.) 

The  function  list->bset  converts  a  set  represented  as  a  list  of  its  elements  into  a 
bit  set.  Its  second  argument  is  the  universe  which  is  to  be  associated  with  the  bit  set 
created.  For  each  element  of  the  list,  the  function  bit-position  is  called  in  order  to 
determine  which  bit  position  should  be  set  to  1.  The  function  ash  is  used  to  create  an 
integer  with  the  correct  bit  set  to  1.  The  function  ReduceF  is  used  to  combine  the  integers 
corresponding  to  the  individual  elements  together  into  a  bit  set  corresponding  to  the  list. 

The  function  bit-position  takes  an  item  and  a  universe  and  returns  the  hit  position 
corresponding  to  the  item.  The  function  operates  in  one  of  two  ways  depending  on 
whether  or  not  the  item  is  in  the  universe.  The  first  line  of  the  function  contains  an  OSS 
expression  which  determines  the  position  of  the  item  in  the  universe.  If  the  item  is  not  in 
the  universe,  the  expression  returns  nil.  (The  function  Rfirst  returns  nil  if  it  is  passed 
a  series  of  length  zero.) 

If  the  item  is  not  in  the  universe,  the  second  line  of  the  function  adds  the  item  onto 
the  end  of  the  universe  and  returns  its  position.  The  extension  of  the  universe  is  done 
be  side-effect  so  that  it  will  be  permanently  recorded  in  the  universe. 

Figure  1.2  shows  the  definition  of  two  OSS  reducers  which  operate  on  OSS  series  of 
hit  sets.  The  first  function  computes  the  union  of  a  series  of  bit  sets,  while  the  second 
computes  their  intersection. 

Live  variable  analysis.  As  an  illustration  of  the  way  hit  sets  might  he  used,  consider 
the  following.  Suppose  that  in  a  compiler,  program  code  is  being  represented  as  blocks 
of  straight-line  code  connected  by  possibly  cyclic  control  flow.  The  top  part  of  Figure  1.3 
shows  the  data  structure  which  re  presents  a  bloek  of  code.  Each  block  has  several  pieces 
of  information  associated  with  it.  Two  of  these  pieces  of  information  are  the  blocks 


(defunS  Rlogior  (bsets) 

(declare  (type  oss  bsets)) 

(ReduceF  0  tt’logior  bsets)) 

(defunS  Rlogand  (bsets) 

(declare  (type  oss  bsets)) 

(ReduceF  -1  O’logand  bsets)) 

Figure  1.2:  Operations  on  OSS  series  of  hit  sets. 
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that  can  branch  to  the  block  in  question  and  the  blocks  it  can  branch  to.  A  program  i- 
represented  as  a  list  of  blocks  that  point  to  each  other  through  these  fields. 

In  addition  to  the  control  flow  information  above,  each  struct  ure  contains  inioniiation 
about  the  way  variables  are  accessed.  In  particular,  it  record-  'lie  variables  'lie  block 
reads  and  the  variables  the  block  writes.  An  additional  field  i  computed  by  the  function 
determine-live  discussed  below)  records  the  variables  uh.h  are  bee  in  the  block.  <A 
variable  is  live  if  it  has  to  be  saved,  because  it  can  potentially  be  used  by  a  following 
block.  I  Finally,  there  is  a  temporary  data  field  which  i-  used  by  functions  (such  as 
determine-live)  which  perform  computations  involved  wth  the  (dock-. 

The  remainder  of  Figure  1.3  shows  the  function  determine-live  which,  given  a  pro 
grain  represented  as  a  list  of  blocks,  determines  the  variables  w  Inch  are  live  in  each  block. 
To  perform  this  computation  efficiently,  the  function  uses  bit  -ets.  I  lie  function  operates 
in  three  steps.  The  first  step  ( convert-to-bsets )  looks  at  each  block  and  sets  up  an 
auxiliary  data  structure  containing  bit  set  representation-  for  the  input  variables,  the 
output  variables,  and  an  initial  guess  that  there  arc  no  live  variables.  (The  integer  0 
represents  an  empty  bit  set.)  This  auxiliary  structure  is  defined  by  the  third  form  in 
Figure  1.3  and  is  stored  in  the  temp  field  of  the  block. 

Ihe  second  step  (perform-relaxation)  determines  which  variables  are  live.  Ibis  is 


done  by  relaxation.  The  initial  guess  that  there  arc  no  live  variables  in  any  block  is 
successively  improved  until  the  correct  answer  is  obtained. 


The  third  step  ( convert -from-bsets )  operates  in  the  reverse  of  the  first  step.  F.aeh 
block,  i-  inspected  and  the  bit  set  representation  of  t lie  live  variables  is  converted  into  a 
list  which  is  stored  in  the  live  field  of  the  block.  The  rest  of  the  temporary  information 
is  discarded. 

On  each  cycle  of  the  loop  in  perform-relaxation.  a  block  i-  examined  to  determine 
whether  its  live  set  has  to  he  changed.  To  do  this,  the  successors  of  the  block  are 
inspected.  Each  successor  needs  to  have  available  to  it  the  variables  it  reads  plus  the 
variables  that  are  live  in  it.  The  total  set  of  variable-  needed  by  all  of  the  successors 
'ogether  is  computed  by  using  Rlogior.  A  new  estimate  of  the  variables  which  are  live 
in  the  current  block  is  obtained  by  taking  the  difference  <  using  logandc2  i  of  the  set  of 
variables  needed  by  the  successors  and  the  variables  written  by  the  current  block. 

If  'his  new  estimate  is  different  from  the  current  estimate  of  what  variables  are  live, 
then  the  estimate  is  changed.  In  addition,  if  the  estimate  is  changed,  perform-relaxation 
has  to  make  sure  that  all  of  the  predecessors  oi  the  current  block  will  be  examined  to 
see  if  the  new  estimate  for  the  current  block  requires  their  live  estimates  to  he  changed. 
This  is  done  by  adding  each  predecessor  onto  the  list  to-do  unle-s  it  is  already  there.  As 
soon  as  the  estimates  of  liveness  stop  changing,  the  cornpui a* ion  can  stop. 

Summary.  The  function  determine-live  is  a  partic  nh-rly  good  example  of  the  wav 
oss  expressions  are  intended  to  he  used  in  two  ways.  First,  oss  expression-  are  used  in  a 
number  of  places  to  express  computations  vv fiich  would  nt herwi.-e  In  expressed  less  <  learlv 
us  loop-  or  less  efficiently  as  sequence  function  expres-ioiis.  "v.  mid.  tin*  main  relaxation 
nliiofit  tun  is  expressed  as  a  loop.  Ibis  is  clone.  be<,v;-o  nx'h'r  oss  expres-ioii-  1  nor 
-oc | ikui ce  function  expressions)  lend  t hemsel ves  to  c-xpre .--mu  il.<  plication  algorithm. 

I  in  -  highlights  the  fact  that  oss  expressions  arc'  not  intended  to  render  loop-  entirely 
obsolete,  but  rat  her  to  provide  a  girat  1  v  unproved  met  inn  1  tor  ■  xprc  .--iiig  t  tie  v  a  - 1  ma  jorit  y 
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(defstruct  (block  (:conc-name  nil)) 


code 

predecessors 

successors 

inputs 

output  s 

live 

temp) 


;The  code  in  the  block. 

;List  of  blocks  that  can  branch  to  this  one. 
;List  of  blocks  this  one  can  branch  to. 

;List  of  variables  read  by  this  block. 

;List  of  variables  written  by  this  block. 
;List  of  variables  that  must  be  stored. 
;Temporary  storage  location. 


(defun  determine-live  (program-graph) 

(let  ((universe  (list  nil))) 

(convert -to-bsets  program-graph  universe) 

(perform- relaxation  program- graph) 

(convert-from-bsets  program-graph  universe)) 
program-graph) 

(defstruct  (temp-bsets  (:conc-name  bset-)) 
inputs  outputs  live) 

(defun  convert-to-bsets  (program-graph  universe) 

(lets  ((block  (Elist  program-graph) ) ) 

(setf  (temp  block) 

(make- temp-bsets 

•.inputs  (list->bset  (inputs  bJock)  universe) 

:outputs  (list->bset  (outputs  block)  universe) 

.■live  0)))) 

(defun  perform-relaxation  (program-graph) 

(let  ((to-do  program-graph)  block  live-estimate) 

(loop  (when  (null  to-do)  (return  (values))) 

(setq  block  (pop  to- do)) 

(lets*  ((next  (Elist  (successors  block))) 

(next-needs  (logior  (bset-inputs  (temp  next)) 

(bset-live  (temp  next)))) 
(total-need  (Rlogior  next-needs))) 

(setq  live-estimate 

(logandc2  total-need  (bset-outputs  (temp  block))))) 
(when  (not  (=  live  estimate  (bset-live  (temp  block)))) 

(setf  (bset-live  (temp  block))  live-estimate) 

(lets  ((prev  (Elist  (predecessors  block)))) 

(pushnew  prev  to-do)))))) 

(defun  convert-from-bsets  (program-graph  universe) 

(lets  ((block  (Elist  program-graph) ) ) 

(setf  (live  block) 

(bset->list  (bset-live  (temp  block))  universe)) 

(setf  (temp  block)  nil))) 

Figure  liS:  I, nr  variable  ;tnalv>i>. 
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2.  Reference  Manual 

1  his  section  is  organized  around  descript imis  of  the  varum-  iunct  ;•  >n.-  .md  •. 
ported  by  the  oss  macro  package.  Kach  description  begin.-  with  w  ;,n  1 

the  arguments  and  results  of  the  function  or  torm  being  *•-•<  1 .  for  e,..,- 

the  headers  are  duplicated  in  Section  ■>.  In  Set  lion  i  he  header-  are  m  1  ;>:..*.■•  * -• 
order  and  show  the  page  where  the  lunctioii  or  form  i-  described. 

!n  a  reference  manual  like  this  one.  it  i>  advar.t  ageniis  t«>  dc-cnbe  .•.««■ i;  •  •’  r  . 

separately  and  completely.  However,  this  inevitably  lead-  '■>  y,  .eiit.tnon  y, 
becati.se  everything  is  related  to  everything  else.  Therefore.  .,ne  cannot  avoid 
things  which  have  not  been  discussed,  (he  rentier  i>  encouraged  -k;p  are. no  i,  •  , 
document  and  to  realize  that  more  than  one  reading  will  probably  ho  net a rv  ;n  •>: 
to  gain  a  complete  understanding  of  the  OSS  macro  package. 

Although  the  following  list  of  OSS  functions  is  large,  it  should  not  be  Taken  a-  >  ■: 
plete.  hvery  effort  has  been  made  to  provide  a  wide  range  of  u-<  ful  predefined  fuin  t  j. . ; 
However,  except  for  a  few  primitive  forms,  all  of  these  fimeiioiis  ctuibl  have  been  defin'd 
by  the  user.  It  is  hoped  that  users  will  write  many  more  such  functions.  \  ke>  r«-a c. 
tor  presenting  a  wide  array  of  predefined  functions  is  to  inspire  u-er-  with  thought- 
the  wide  variety  of  functions  they  can  write  for  them-eives. 

Restrictions  and  Definitions  of  Terms. 

\s  alluded  to  in  Section  1.  there  art  a  number  of  restriction'  which  uss  >-\ ;>re-si. m . 

hav  1  o  obey.  The  OSS  macro  package  is  designetl  so  t hat  nii  !>ut  tic. . ihno,  '.e.'-nctiou- 

are  impossible  to  violate  with  the  facilities  provided  \-  .»  r-'-ult.  t  •  programmer  need 
not  think  about  these  restrictions  at  all. 

The  Oss  macro  package  checks  to  see  that  t  lie  remainin'.:  •  hr-.-  restrictions  are  obev.-d 
on  an  expression  by  expression  basis.  Whenever  t hey  ire  violated,  an  error  message  i- 
issued.  There  is  no  need  for  programmers  to  worry  about  these  :  rici imis  until  one  of 
these  errors  occurs.  However,  when  such  an  error  occur.-.  :  iie  > Mending  expression  has 
fe  rearranged  in  order  to  alleviate  the  problem. 

(liven  that  simple  OSS  expressions  are  very  unlikely  to  violate  anv  of  the  restrictions, 
it  is  reasonable  to  skip  this  section  when  fir-t  reading  tin-  manual.  However,  it  is  useful 
to  mad  this  section  before  trying  to  debug  complex  oss  expressions. 

I  he  discussion  below  starts  by  defining  two  key  terms-  loti  line  functions  and  carlv 
eo mmi'iou  i  which  are  used  1o  categorize  the  oss  functions  described  in  the  rest  of  this 
'  a:  1  he  discussion  then  continue-  by  brief? v  de-t  ribmg  tl.e  three  re-trn  tiotis  which 

'to  violated.  'See  ti  for  a  complete  di-<  us.-ioii  oj  ,d!  tin'  restrictions,  i 

On-line  and  ofF-lme.  Suppose  that  /  i-  an  os-  tarn  i  ion  w  hich  read-  one  or  more 
"re  -  nput-and  write-  one  or  more  -erics  output-  1  c  ■  'notion  f  i-  miliih'  I  if  u 
operates  hi  t  tie  following  fa-hion.  first.  /  re. ids  m  the  ar  t  element  ,,f  each  input  -era  -, 
‘her  !’  vrites  out  the  lir-l  eh  rueni  of  each  output  -on  -.  then  n  re. id-  in  the  second 
e  emeri',  of  e;teh  input  -cries,  then  it  'Antes  out  tile  -econ-t  element  o',  each  output  -eric-, 
and  o  -in.  In  addition,  j  musi  imiii'',|i.,ir  i\  leniiiaai'  as  ~ ■  > i <  c-  .tm  input  rum-  out  of 
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elements.  If  a  /  is  not  on-line.  thru  h  is  off-line. 

In  the  context  ot  OSS  expressions,  the  term  on-line  is  generalized  so  that  it  applies 
to  individual  oss  input  and  output  port-,  in  addition  to  whole  oimtions.  An  uss  port 
is  on-line  iff  the  processing  <it  t  hat  port  always  tollows  the  rigidly  -s  nehronized  pattern 
deserihed  above.  Otherwise,  it  is  of!  line.  From  this  point  < >}  view,  a  function  is  <m  line 
ill’  all  of  its  OSS  ports  are  on-line. 

The  prototypical  example  of  an  on-line  oss  function  is  TmapF  (which  map-  a  function 
over  a  series).  Each  time  it  reads  an  input  •dement  it  applies  ‘he  mapped  tunet'on  to 
it  and  writes  an  output  element.  In  contrast,  the  function  Tremove -dupii cates  1  winch 
removes  the  duplicate  elements  from  a  series)  is  not  on-line.  Since  some  of  i  he  input 
elements  do  not  become  output  elements,  it  is  not  possible  for  Tremove-dupl  tcates  to 
write  an  output  element  every  time  it  reads  an  input  element. 

For  every  OSS  function,  the  documentation  below  specifics  wnicl.  ports  are  on-line 
and  which  are  off-line.  In  this  regard,  it  is  interesting  to  note  that  every  function  which 
has  only  one  OSS  port  (e.g..  enumerators  with  only  one  output  and  reducer-  with  only 
one  input  I  are  trivially  on-line.  The  only  oss  functions  which  have  ulf-liue  port-  aie 
t  ransducers. 

Early  termination.  An  important  feature  of  OSS  functions  is  the  -dilations  under 
which  they  terminate.  The  definition  of  on-line  above  requires  that  on-line  func!  ion  - 
must  terminate  as  soon  as  any  series  input  runs  out  of  elements,  if  an  OS1-  function  can 
terminate  before  any  of  its  inputs  are  exhausted,  then  it  is  an  early  terminator.  1  he 
degenerate  case  of  functions  which  do  not  have  any  series  inputs  (i.e..  enumerators)  is 
categorized  by  saying  that  enumerators  are  early  terminators  iff  they  can  terminate. 

As  an  example  of  an  early  terminator,  consider  the  function  TuntilF  (which  reads  a 
series  and  returns  all  of  the  elements  of  that  series  up  to.  but  not  including,  the  first 
element  which  satisfies  a  given  predicate).  This  function  is  an  early  terminator,  because 
it  can  terminate  before  the  input  runs  out  of  elements. 

The  documentation  below  specifies  which  functions  are  early  terminators.  Besides 
enumerators,  their  are  only  7  OSS  functions  which  are  early  terminators. 

Isolation.  A  data  flow  arc  6  in  an  oss  expression  A  is  isolated  iff  it  is  possible  to 
partition  the  functions  in  A"  into  two  parts  Y  and  )  in  such  a  way  that:  goes  from  i 
to  Y.  there  is  no  OSS  data  flow  from  V  to  V.  and  there  is  no  data  flow  from  )  to  Y. 
For  example,  consider  the  OSS  expression  (lets  ((x  (f  y)))  (i  (h  x  (g  x))))  which 
corresponds  to  the  graph  in  Figure  2.1. 


(  he  data  flow  arc  M  i-  isolated,  lo  -how  this  one  merely  has  to  partition  the  expres¬ 
sion  so  t  fiat  f .  g.  and  h  are  on  one  side  and  i  is  ori  t  he  ot  her.  I  he  question  of  whet  her  or 
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isolated.  As  an  example  of  an  expression  where  this  i-  not  true,  consider  the  following. 
In  this  expression,  the  data  flow  implemented  In  t  lit'  variable  total  is  not  isolated. 

;Signals  error  16 


(letS*  ((nums  (Evector  #(3  2  8))) 

(total  (ReduceF  0  #’+  nums))) 
(Rvector  (/  nums  total))) 


(The  basic  problem  here  is  that  while  the  elements  created  by  Evector  are  being  used 
to  compute  total,  they  all  have  to  be  saved  so  that  they  can  be  used  again  later  in 
order  to  perform  the  indicated  divisions.  Eliminating  the  need  for  such  storage  is  the  key 
source  of  efficiency  underlying  OSS  expressions.) 

Off-line  OSS  ports  must  be  isolated.  In  order  for  an  OSS  expression  to  be  reliable 
converted  into  a  highly  efficient  loop,  every  off-line  port  must  be  isolated.  As  an  example 
of  an  expression  which  has  an  off-line  output  which  is  not  isolated,  consider  the  following. 
In  this  expression,  the  data  flow  implemented  by  the  variable  positions  is  not  isolated. 

(letS*  ((keys  (Elist  list))  iSignals  error  17.1 

(positions  (Tpositions  keys))) 

(Rlist  (list  positions  keys))) 

i  Ihe  basic  problem  here  is  that  since  Tpositions  .'kip-  null  element.-  of  the  input. 
Tpositions  'ometimes  has  to  read  several  input  element-  before  it  can  produce  the  next 
output  element.  This  forces  an  unpredictable  number  of  elements  of  keys  to  be  -aved  -o 
rli.it  they  can  be  used  later  when  creating  li-t-.  \-  almve.  eliminating  the  need  for  -mb 
-’orage  i>  the  main  goal  of  OSS  expression-.! 

Code  copying.  If  an  OSS  expression  violate-  either  the  above  re-t action-,  tin 
problem  .  an  always  be  fixed  by  copying  code  until  the  d.it.i  flow  or  port  in  <|ue-tm,i 
become-  isolated.  For  instance,  the  example  above  o|  an  os-  expression  in  w'mb  i 
nmi  ()SS  data  flow  Is  not  isolated  can  be  fixed  a-  follow- 
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(lat5*  ((nums  (Evector  #(3  2  8))) 

(total  (ReduceF  0  #’+  (Evector  #(3  -2  8))))) 

(Rvector  (/  muns  total'1!’)  ~i-  #(3/13  2/13  8/13) 

It  would  he  possible  }.ir  the  oss  macro  package  to  automatically  copy  code  whenever 
eith  er  ot  the  isolation  restrictions  i*  violated.  However,  this  is  not  done  tor  two  reason*, 
hirst,  it  -ode- effect  <  i  e.u  ,  input  or  output  i  an*  m  voiced .  code  copying  may  not  !*#•  correct 
ne>*  pre'erving.  Second,  large  niiiimnt.  of  code  sunn  times  have  to  he  copied  and  that 
can  introduce  large  amounts  ol  extra  computation. 

A  major  goal  ot  OSS  expressions  is  ensuring  that  expressions  which  look  simple  to 
compute  actually  are  simple  to  compute.  Automatically  introducing  large  amount-  ot 
additional  computation  without  the  programmer's  knowledge  would  violate  this  goal. 
At  the  very  least,  leaving  code  copying  to  programmers  makes  them  aware  of  what  is 
expensive  to  compute  and  what  is  not.  Looked  at  from  a  more  positive  perspective, 
it  encourages  them  to  think  oi  ways  to  compute  what  they  want  without  doing  code 
copying. 

For  instance,  consider  the  the  example  above  of  an  OSS  expression  in  which  an  off  din*' 
port  is  not  isolated.  It  might  tie  that  case  that  the  programmer  knows  that  list  does 
not  contain  any  mil!  elements,  and  that  Tpositions  is  therefore  merely  being  user!  to 
enumerate  what  the  positions  of  the  elements  are.  In  this  situation,  the  expression  can 
lie  fixed  as  follows,  which  does  not  require  any  code  copying.  (  !  he  key  insight  here  is 
that  the  positions  do  not  actual  depend  on  the  values  in  the  list.) 

(letS*  ((keys  (Elist  ’(a  b  c))) 

(positions  (Eup  0))) 

(Rlist  (list  positions  keys)))  =>  ((0  a)  (l  b)  (2  c)) 

i  It  is  interesting  to  note  that  if  an  expression  is  a  tree  (as  opposed  to  a  graph  as 
in  Figure  2.1).  then  every  data  flow  arc  and  every  port  is  isolated.  This  is  why  OSS 
expressions  which  do  not  contain  variables  bound  by  lets,  lambdas,  or  defunS  cannot 
violated  either  of  the  isolation  restrictions.  This  is  also  why  code  copying  can  always  fix 
any  violation  code  copying  can  convert,  any  graph  into  a  tree.) 

On-line  subexpressions.  The  two  isolation  restrictions  above  permit  a  divide  and 
conquer  approach  to  ’tic  processing  of  oss  expressions.  If  an  OSS  expression  obeys  the 
isolation  restrictions,  then  it  can  be  repeatedly  partitioned  until  all  of  the  data  flow  in 
each  subexpression  goes  from  an  on-line  output  to  an  on-line  input.  The  subexpressions 
which  remain  after  partitioning  are  referred  to  as  on-linr  subexpressions. 

Termination  points.  Hie  functions  in  each  on-line  subexpression  can  be  divided 
it. to  two  chts'e-:  those  which  are  terminal  ion  points  and  those  which  are  not.  A  function 
is  a  termination  point  if  it  can  terminate  before  any  other  function  in  the  subexpression 
terminate-..  1  here  are  two  realms  lor  functions  being  termination  points.  Functions 
which  are  eariv  terminators  are  always  termination  points.  In  addition,  any  function 
which  read*  ,ni  oss  series  which  come.*  from  a  different  on-line  subexpression  is  a  termi- 
i  it  ion  pom* . 

Data  How  paths  between  termination  points  and  outputs.  In  order  for  an 
oss  expression  to  be  reliably  converted  into  a  highly  efficient  loop,  it  must  be  the  case 
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that  within  each  on-line  subexpression.  there  t-  .1  1l.1t  0  1 1  •  *  path  '  r>  >  1 1 1  each  terminal  inn 
point  to  each  output.  As  art  example  of  an  oss  expression  for  which  this  property 

does  not  hold,  consider  the  following.  Partitioning  divide-  this  expression  into  two  on¬ 

line  subexpressions,  one  containing  list  and  <m<  containing  everything  else.  In  tin' 
large  on  line  subexpression,  the  two  instances  ot  Evector  ar<  termination  points  I  he 
program  is  erroneous,  because  there  is  no  data  the.-,  path  Iron  the  termination  point 
(Evector  weight-vector)  to  the  output  ot  (Rvector  squares). 

(lets*  ((values  (Evector  value- vector ) )  iSignals  error  18 

(weights  (Evector  weight  -  vector ) 1 
(squares  (*  values  values)) 

(weighted-squares  («  squares  weights') 

(list  (Rvector  squares)  (Rvector  weighted  -  squares 1 )  t 

(  I  he  basic  problem  here  is  that  it  the  number  of  eje  e.-.t  •  •  value  vector  :  -  g  r<  -a ' «  r 

than  t  he  number  of  elements  in  weight  -  vector .  tie  <  .  m.  p  ,:t  .it  .u  ,  1  squares  u  •  a;  ,d  have 

to  continue  even  after  the  computation  of  weighted- squares  ■  1-  b.-ep  complete.1,  I  hi- 
kind  ol  partial  continuing  evaluation  is  not  supported  b\  its  u  r*.  package.  became 

it  was  judged  t  hat  it  requires  too  much  overhead  m  <>;■ , !<■-  t, .  .  .  uu  r  •  a  ha '  get  -  ■.  a  luated 

when. ) 

When  an  OSS  expression  violates  the  restriction  at*..  .  .  • !  r  '  ■  r>-.-  .tporoache-  to 
fixing  the  problem:  reducing  the  number  of  termination  m ••  ■  •  ■ ; i ■  re.»  .ng  1  h<  cmiiec 

tivity  between  termination  points  and  outputs,  and  ■  i «  •  ;  • .  1  - 1 : .  _  'tie  , umbel  <<f  •  mi  put  - . 

The  easiest  way  to  decrease  the  number  o|  teriuin.it ton  pia:.'-  1-  to  replace  earl) 
terminators  by  equivalent  operations  which  are  not  earl)  terminators  1  for  example,  see 
page  3fi).  If  an  early  terminator  is  not  an  enumerator,  then  this  can  alway-  be  done 
without  difficultly.  The  documentation  below,  describes  a  non  earl}  variant  for  each 
early  terminating  transducer  and  reducer,  i!  multiple  .•numerators  are  the  problem  1  as  in 
the  example  above)  decreasing  the  number  of  termination  points  is  usually  not  practical. 
However,  sometimes  an  enumerator  which  terminates  can  be  replaced  by  an  enumerator 
which  ne\er  terminates. 

The  connectivity  between  termination  points  and  outputs  can  lie  increased  by  using 
the  function  Tcotruncate.  .As  discussed  on  page  2b.  this  is  the  preferred  way  to  fix  the 
problem  in  the  example  above. 

If  worst  comes  to  worst,  code  copying  can  always  be  used  to  hx  the  problem.  It  is 
impossible  for  an  on-line  subexpression  to  \  iolate  t  he  rest  net  ion  abo\e  unless  it  computes 
two  different  outputs.  This  in  turn  is  impossible  unless  the  OSS  expression  as  a  whole 
contains  variables  bound  by  lets,  lambdas,  or  defunS.  Code  copying  can  always  be  used 
to  break  the  subexpression  in  question  into  two  parts  each  of  which  computes  one  of  the 
outputs. 


General  Information 

Before  discussing  the  individual  oss  functions  iti  detail,  a  few  general  comments  are 
in  order.  !•  irst .  all  of  t  he  oss  In  ml  ions  and  tor  m  s  are  defined  in  t  lie  package  OSS.  To  make 
these  names  easik  accessible  me  the  p,i,  knge  OSS  ft.",  evaluate  (use-package  "OSS")  I 
If  this  is  not  clone,  the  names  will  have  t<>  be  prefixed  with  "oss:'  when  they  are  used. 


,  **.  - 
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Naming  conventions.  I  hr  names  of  the  various  OSS  functions  and  forms  follow  a 
strict  naming  convention.  I  fie  lir-t  letter  of  an  OSS  function  name  indicates  the  type  of 
function  as  shown  below.  The  fetter  codes  are  written  in  upper  case  in  this  document 
lease  does  not  matter  to  Common  Lisp)  and  each  letter  is  intended  to  be  pronounced  as 
a  separate  syllable. 

E  Knumerator. 

T  transducer. 

R  Reducer. 

1  he  last  letter  of  each  oss  special  form  is  "S".  In  general,  this  indicates  that  the  form 
is  primitive  in  the  sense  that  it  could  not  be  defined  by  the  user.  Some  OSS  functions 
end  in  the  letter  "F  .  This  is  used  to  indicate  that  the  function  is  a  higher-order  function 
which  takes  functions  as  arguments. 

I  he  naming  convention  has  two  advantages:  one  trivial  but  vital  and  the  other  more 
fundamentally  useful.  First,  many  ol  the  OSS  functions  are  very  similar  to  standard 
(  ommon  Lisp  sequence  functions.  As  a  result,  it  makes  sense  to  give  them  similar  names. 
However,  it  is  not  possible  to  give  them  exactly  the  same  names  without  redefining  the 
standard  (unctions.  The  naming  convention  allows  the  names  to  be  closely  related  in  a 
predictable  way  without  making  the  names  unreasonably  long. 

Second,  the  naming  convention  highlights  several  properties  of  OSS  functions  which 
make  it  easier  to  read  and  understand  OSS  expressions.  In  particular,  the  prefixes  high¬ 
light  the  places  where  series  are  created  and  consumed. 

1  he  names  of  arguments  and  results  of  OSS  functions  are  also  chosen  following  naming 
conventions.  First,  all  of  the  names  are  chosen  in  an  attempt  to  indicate  type  restrictions 
(e.g..  number  indicates  that  an  argument  must  be  a  number;  item  indicates  that  there  is 
no  type  restriction).  Plural  names  are  used  iff  the  value  in  question  is  an  OSS  series  (e.g.. 
numbers  indicates  an  OSS  series  of  numbers:  items  indicates  an  OSS  series  of  unrest ricted 
values ).  1  he  name  of  a  series  input  or  output  begins  with  “0"  iff  it  is  off-line. 

OSS  series.  Two  general  points  about  OSS  series  are  worthy  of  note.  First,  like 
Common  Lisp  sequences,  OSS  series  use  zero-based  indexing  (i.e.,  the  first  element  is  the 
Oth  element).  Second,  unlike  Common  Lisp  sequences.  OSS  series  can  be  unbounded  in 
length. 

Tutorial  mode.  A  prominent  feature  of  the  various  descriptions  is  that  they  contain 
many  examples.  These  examples  contain  large  numbers  of  OSS  series  as  inputs  and 
outputs.  In  the  interest  of  brevity,  the  notation  [. . .  ]  is  used  to  indicate  a  literal  OSS 
'cries.  If  the  last  entry  in  a  literal  oss  series  is  an  ellipsis,  this  indicates  that  the  OSS 
series  is  unbounded  in  length. 

[12  3] 

[a  b  (c  d)] 

[T  nil  T  nil  .. .] 

1  he  notation  [. . .  3  is  not  supported  by  the  OSS  macro  package.  It  would  be  straight 
forward  to  do  so  by  using  set-macro-character.  Perhaps  even  better,  one  could  use 
set-dispatch-macro-character  to  support  a  notation  #[...]  analogous  to  #(...  ).  How 
ever,  although  literal  series  are  very  useful  in  the  examples  h'dow,  experience  suggests 
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that  literal  series  are  seldom  useful  when  writing  actual  program*.  Inasmuch  as  this  is 
the  case,  it  was  decided  that  it  was  unwise  to  use  up  one  of  the  small  set  of  characters 
which  are  available  for  user-defined  reader  macros  or  user-defined  #  dispatch  characters. 

M  any  of  the  examples  show  OSS  expressions  returning  OSS  series  as  their  values. 
However,  one  should  not  take  this  literally.  If  these  examples  are  typed  to  Common  I.isp 
as  isolated  expressions,  they  will  not  return  any  values.  This  is  so.  because  the  OSS  macro 
package  does  not  allow  complete  OSS  expressions  to  return  OSS  series.  The  examples  are 
intended  to  show  what  would  be  returned  if  the  example  expressions  were  nested  in  larger 
expressions. 

•  oss-tutorial-mode  ^optional  (  T  or  nil  T)  state-of-t uforiaf-mcu'e 

The  above  not  withstanding,  the  OSS  macro  package  provides  a  special  tutorial  mode 
in  which  the  notation  [. . .  ]  is  supported  and  OSS  expressions  can  return  (potentially 
unbounded)  OSS  values.  However,  these  values  still  cannot  be  stored  in  ordinary  variables. 
This  mode  is  entered  bv  calling  the  function  oss-tutorial-mode  with  an  argument  of  T. 
Calling  the  function  with  an  argument  of  nil  turns  tutorial  mode  off. 

Using  tutorial  mode,  it  is  possible  to  direct  1\  duplicate  the  examples  shown  below. 
However,  tutorial  mode  is  very  inefficient.  What  is  worse,  tutorial  mode  introduces  non¬ 
correctness-preserving  changes  in  OSS  expressions.  (For  example,  in  order  to  correctly 
duplicate  the  examples  that  illustrate  error  messages  about  non-terminating  expressions 
and  the  fact  that  OSS  series  are  not  actually  returned  by  complete  OSS  expressions, 
tutorial  mode  must  be  turned  off.)  All  in  all,  it  is  important  that  tutorial  mode  not  be 
used  as  anything  other  than  an  educational  aid. 

OSS  functions  are  actually  macros.  Every  OSS  function  is  actually  a  macro.  As 
a  result.  OSS  functions  cannot  be  funcall'ed.  or  apply'ed.  When  the  user  defines  new 
OSS  functions,  they  must  be  defined  before  the  first  time  they  are  used.  Also,  when  an 
OSS  function  takes  keyword  arguments,  the  keywords  must  be  literals.  They  cannot  be 
expressions  which  evaluate  to  keywords  at  run  time. 

Finally,  the  macro  expansion  processing  associated  with  OSS  expressions  is  relatively 
time  consuming.  In  order  to  avoid  this  overhead  during  the  running  of  a  user  program, 
it  is  important  that  programs  containing  OSS  expressions  be  compiled  rather  than  run 
interpreti  vely. 

A  minor  advantage  of  the  fact  that  everything  in  the  oss  macro  package  is  a  macro 
is  that  once  a  program  which  uses  the  macro  package  is  compiled,  the  compiled  program 
can  subsequently  be  run  without  having  to  load  the  oss  macro  package. 

A  more  important  advantage  of  the  fact  that  everything  in  the  OSS  macro  package  is 
a  macro  is  that  quoted  macro  names  can  be  used  as  functional  arguments  to  higher-order 
oss  functions.  (In  contrast,  quoted  macro  names  cannot  be  used  as  functional  arguments 
to  higher-order  Common  Lisp  functions  such  as  reduce.!  Although  this  may  appear  to 
be  a  minor  benefit,  it  is  actually  quite  useful. 

Enumerators 

Enumerators  create  OSS  outputs  based  on  non  OSS  inputs.  There  are  two  ba*’c  kinds 
of  enumerators:  ones  that  create  an  osS  series  based  on  some  formula  (e.g.,  enumerating 


Enumerator:* 


Jj 
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a  sequence  of  integers)  and  ones  that  create  an  OSS  series  containing  the  elements  of  an 
aggregate  data  structure  ie.g..  enumerating  the  elements  of  a  list).  All  the  predefined 
enumerator;,  are  on-line.  In  general  the\  arc  all  earl\  t  .-rm  ill  a  t  nr<  However,  a-  noted 
:>elo w .  in  some  situations  some  enumerators  produce  unhounded  outputs  and  are  not 
early  terminators. 

•  Eoss  t rest  e.vpr  -list  — -  items 

I  he  expr  list  consists  of  zero  or  more  expressions.  I  he  function  Eoss  creates  an  Oss 
series  containing  the  values  of  t  heso  expressions.  Kvery  expression  in  expr-list  is  evaluated 
before  the  first  output  element  is  returned. 


(Eoss  1 
(Eoss)  : 


[l  a  b] 


To  get  the  effect  of  delaying  the  evaluation  of  individual  elements  until  they  are 
needed,  it  is  necessary  to  define  a  special  purpose  enumerator  which  computes  the  indi¬ 
vidual  items  as  needed.  However,  due  to  the  control  overhead  required,  this  is  seldom 
wort  hw  bile. 

It  is  possible  for  the  expr-list  to  contain  an  instance  of  :R.  (This  must  be  a  literal 
instance  of  :R.  not  an  expression  whi'di  evaluates  to  :R.)  If  this  is  the  case,  then  Eoss 
produces  an  unbounded  OSS  series  analogous  to  a  repeating  decimal  number.  The  output 
consists  of  the  values  of  the  expressions  preceding  the  :R  followed  by  an  unbounded 
number  of  repetitions  of  t he  values  following  the  :R,  if  t here  are  any  such  values.  (In  this 
situation.  Eoss  is  not  an  early  terminator.) 

(Eoss  1  ’a  : R  ’b  ’c)  [labebebe  ...] 

(Eoss  T  : R  nil)  =>  [T  nil  nil  nil  ...] 

(Eoss  1  : R)  =>  [l] 

(Eoss  :R  1)  =>  [i  l  l  ..  .] 

•  Eup  ^optional  (start  0)  ftkey  (  :  by  1)  :to  ibelow  :  length  =>  numbers 

This  function  is  analogous  to  the  Loop  macro  2  numeric  iteration  clause.  It  creates 
an  OSS  series  of  numbers  starting  with  start  and  counting  up  by  :by.  The  argument 
start  is  optional  and  defaults  to  integer  0.  The  keyword  argument  :by  must  always  be  a 
positive  number  and  defaults  to  integer  1. 

There  are  four  kinds  of  end  tests.  If  :to  is  specified,  stepping  stops  at  this  number. 
The  number  :to  will  be  included  in  the  OSS  series  iff  (-  :to  start)  is  a  multiple  of  :by. 
If  ibelow  is  specified,  things  operate  exactly  as  if  :to  were  specified  except  that  the 
number  ibelow  is  never  included  in  the  OSS  series.  If  -.length  is  specified,  the  OSS  series 
hn>  length  ilength.  It  must  be  the  case  that  ilength  isa  non- negative  integer.  If  ilength 
i>  positive,  the  last  element  of  the  OSS  series  will  be  (+  start  (*  :by  (1-  : length))).  If 
none  of  the  termination  arguments  are  specified,  the  output  has  unbounded  length.  (In 
this  -ituation.  Eup  is  not  an  early  terminator.)  If  more  than  one  termination  argument 
is  specified,  it  is  an  error. 

(Eup  :to  4)  =>  [0  1  2  3  4] 

(Eup  :to  4  : by  3)  =>  [0  3] 

(Eup  1  ibelow  4)  [l  2  3] 

(Eup  4  : length  3)  =>  [45  6] 

(Eup)  =>  [01234...] 


£1 
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As  shown  in  the  following  example.  Eup  does  not  assume  that  the  numbers  being 
enumerated  are  integers. 

(Eup  1.5  : by  .1  : length  3)  =>  [1.5  1.6  1.7] 

e  Edown  ioptional  (start  0)  4key  (:by  1)  :to  :above  :length  =>  numbers 

The  function  Edown  is  analogous  to  Eup.  except  that  it  counts  down  instead  of  up  and 
uses  the  keyword  : above  instead  of  : below. 

(Edown  :to  -4)  =>  [0  -1  -2  -3  -4] 

(Edown  :to  -4  : by  3)  =>  [0  -3] 

(Edown  1  :above  -4)  =>•  [l  0  -1  -2  -3] 

(Edown  4  : length  3)  =>  [432] 

(Edown)  =>  [0  -1  -2  -3  -4  .  . .  ] 

(Edown  -1.5  :by  .1  : length  3)  [-1.5  -1.6  -1.7] 

e  Esublists  fist  ^optional  (end-test  tt’endp)  =>  suhli>ts 

This  function  creates  an  OSS  series  containing  the  successive  subiists  of  list.  The  end- 
test  must  be  a  function  from  objects  to  boolean  values  (i.e.,  to  null/non-null ).  It  is  used 
to  determine  when  to  stop  the  enumeration.  Successive  cdrs  are  returned  up  to,  but  not 
including,  the  first  one  for  which  end  rest  returns  non  null. 

(Esublists  ’(a  b  c))  =>  [(a  b  c)  (b  c)  (c)] 

(Esublists  ’(a  b  .  c)  #’atom)  =>  [(a  b  .  c)  (b  .  c)] 

The  default  end-test  (i’endp)  will  cause  Esublists  to  blow'  up  if  list  contains  a  non- 
list  cdr.  More  robust  enumeration  can  be  obtained  by  using  the  end-test  tf'atom  as  in  the 
second  example  above.  The  assumption  that  list  will  end  with  nil  is  used  as  the  default 
case,  because  the  assumption  sometimes  allows  programming  errors  to  be  detected  closer 
to  their  sources. 

•  Elist  list  toptional  (end-test  tt’endp)  =>  elements 

This  function  creates  an  OSS  series  containing  the  successive  elements  of  list.  It  is 
closely  analogous  to  Esublists  as  shown  below.  In  particular,  end-test  has  the  same 
meaning  and  the  same  caveats  apply. 

(Elist  ’(a  b  c))  =>  [a  b  c] 

(Elist  ’())  □ 

(Elist  ’(a  b  .  c)  #’atom)  =>  [a  b] 

(Elist  list)  =  (car  (Esublists  list)) 

The  value  returned  by  Elist  can  be  used  as  a  destination  for  alters. 

(let  ( ( list  ’ (a  b  c) ) ) 

(alters  (Elist  (cdr  list))  (Eup)) 
list)  =>  (a  0  1) 
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•  Ealist  alist  ^optional  (test  #’eql)  ->  keys  value s 

l  his  function  returns  two  oss  series  containing  keys  and  their  associated  values.  1'he 
first  ('lenient  of  frees  is  the  key  m  th>’  first  »-ntr\  mi  abst.  the  firO  ••Ienieui  of  value'-  i'  the 
value  in  the  first  entry,  and  so  on.  I  he  a  list  must  be  a  proper  list  ending  m  nil  and  each 
entry  in  alist  must  be  a  cons  cell  or  nil.  hike  assoc.  Ealist  skip*  entries  which  are  nil 
and  entries  which  have  the  same  key  as  an  earlier  entry.  I  he  test  argument  i-  used  to 
determine  when  two  keys  are  the  same. 

(Ealist  ’((a  .  1)  ()  (a  .  3)  (b  .  2)))  =>  [a  b]  [l  2] 

(Ealist  nil)  =>  []  [] 

Both  of  the  series  returned  by  Ealist  can  be  used  as  destinations  tor  alters.  !  In 
analogy  with  multiple-value-bind,  lets  can  be  used  to  bind  both  values  returned  by 
Ealist. ) 

(let  ((alist  ’((a  .  l)  (b  .  2)))) 

(letS  (((key  val)  (Ealist  alist))) 

(alters  key  (list  key)) 

(alters  val  (1+  val))) 
alist)  =S>  ’(((a)  .  2)  ((b)  .  3)) 

The  OSS  function  Ealist  is  forced  to  perform  a  significant  amount  of  computation  in 
order  to  check  that  no  duplicate  keys  or  null  entries  are  being  enumerated.  In  a  situation 
where  it  is  known  that  no  duplicate  keys  or  null  entries  exist,  it  is  much  more  efficient  to 
use  Elist  as  shown  below. 

(lets*  ((e  (Elist  ’((a  .  1)  (b  ,  2)))) 

(keys  (car  e)) 

(values  (edr  e) ) ) 

(Rlist  (list  keys  values)))  =t>  ((a  1)  (b  2)) 

•  Eplist  plist  =>  indicators  values 

This  function  returns  two  oss  series  containing  indicators  and  their  associated  values. 
The  first  element  of  indicators  is  t lie  first  indicator  in  the  plist .  the  first  element  of  values 
is  the  associated  value,  and  so  on.  The  plist  argument  must  be  a  proper  list  of  even 
length  ending  in  nil.  In  analog}  with  the  way  get  works,  if  an  indicator  appears  more 
than  once  in  plist,  it  (and  its  value)  will  only  be  enumerated  the  first  time  it  appears. 
(Moth  of  the  OSS  series  returned  by  Eplist  can  be  used  as  destinations  fur  alters.  I 

(Eplist  ’(a  1  a  3  b  2))  [a  b]  [l  2] 

(Eplist  nil)  =>  []  [] 

The  oss  function  Eplist  has  to  perform  a  significant  amount  of  computation  in  order 
to  check  that  no  duplicate  indicators  are  being  enumerated.  In  a  situation  where  it  is 
known  that  no  duplicate  indicator'  exist.  it  is  much  more  efficient  to  use  EnumerateF  as 
shown  below. 

(letS*  ((e  (EnumerateF  ’(a  1  b  2)  # ’ eddr  #’null)) 

(indicators  (car  e)) 

(values  (cadr  e))) 

(Rlist  (list  indicators  values)))  =>  ((a  b)  (1  2)) 


18 


Reference  Manual 


I 


•  Etree  free  ^optional  ( leaf-test  #’atom)  =>  nodes 

This  function  creates  an  OSS  series  containing  all  of  the  nodes  in  tree.  Ihe  function 
assumes  that  free  is  a  tree  built  of  lists,  where  each  node  is  a  list  and  the  element s  in 
the  list  are  the  children  of  the  node.  I'he  function  Etree  does  not  assume  that  the  node 
lists  end  in  nil;  however,  it  ignores  any  non  list  cdrs.  (This  behavior  increases  the  utility 
of  Etree  when  it  is  used  to  scan  Lisp  code.)  The  nodes  in  the  tree  are  enumerated  in 
preorder  (i.e..  first  the  root  is  output,  then  the  nodes  in  the  tree  which  is  the  first  child 
of  the  root  is  enumerated  in  full,  then  t he  nodes  in  the  tree  which  is  the  second  child  of 
the  root  is  enumerated  in  full,  etc.). 

The  leaf  test  is  used  to  decide  which  elements  of  the  tree  are  leaves  as  opposed  to 
internal  nodes.  Failure  of  the  test  should  guarantee  that  the  element  is  a  list.  By  default. 
leaf-test  is  #’atom.  This  choice  of  test  categorizes  nil  as  a  leaf  rather  than  as  a  node 
with  no  children. 

The  function  Etree  assumes  that  free  is  a  tree  as  opposed  to  a  graph.  If  tree  is  a 
graph  instead  of  a  tree  (i.e.  some  node  has  more  than  one  parent),  then  this  node  (and 
its  descendants)  will  be  enumerated  more  than  once.  If  the  tree  is  a  cyclic  graph,  then 
the  output  series  will  be  unbounded  in  length. 

(Etree  ’d)  =>  [d] 

(Etree  ’((c)  d))  =>  [((c)  d)  (c)  c  d] 

(Etree  ’((c)  d) 

#’ (lambda  (e) 

(or  (atom  e)  (atom  (car  e)))))  =>  [((c)  d)  (c)  d] 

e  Efringe  tree  ^optional  {leaf  test  tt’atom)  leaves 

This  enumerator  is  the  same  as  Etree  except  that  it  only  enumerates  the  leaves  of 
the  tree,  skipping  all  internal  nodes.  The  logical  relationship  between  Efringe  and  Etree 
is  shown  in  the  first  example  below.  However.  Efringe  is  implemented  more  efficiently 
than  this  example  would  indicate. 

(Efringe  tree)  EE  (TselectF  tt’atom  (Etree  tree)) 

(Efringe  ’d)  =>  [d] 

(Efringe  ’((c)  d))  =>  [c  d] 

(Efringe  ’((c)  d) 

•’(lambda  (e) 

(or  (atom  e)  (atom  (car  e)))))  =>  [(c)  d] 

The  value  returned  by  Efringe  can  be  used  as  a  destination  for  alters.  However,  if 
the  entire  tree  is  a  leaf  and  gets  altered,  this  will  have  no  side-effect  on  the  tree  as  a  whole. 
In  addition,  altering  a  leaf  will  have  no  effect  on  the  leaves  enumerated.  In  particular,  if 
a  leaf  is  altered  into  a  subtree,  the  leaves  of  this  subtree  will  not  get  enumerated. 

(let  ((tree  ’((3)  4))) 

(lets  ((leaf  (Efringe  tree))) 

(if  (evenp  leaf)  (alters  leaf  (-  leaf)))) 
tree)  ((3)  -4) 

•  Evector  vector  ^optional  (indices  (Eup))  =>  elements 

I  his  (unction  creates  an  OSS  series  of  the  elements  of  a  one-dimensional  array.  If 
indices  assumes  its  default  value.  Evector  enumerates  all  of  the  elements  of  vector  in 
order. 
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(Evector  "BAR")  =>  [#\B  #\A  #\R] 

(Evector  "“)  [] 

Looked  al  in  greater  detail.  Evector  enumerates  the  elements  ul  vector  winch  are 
indicated  by  the  elements  of  the  OSS  series  indices.  The  indices  must  he  non- negative 
integers,  however,  they  do  not  have  to  he  in  order.  Enumeration  stops  when  indices  runs 
out.  or  an  index  greater  than  or  equal  to  the  length  of  vector  is  encountered.  One  can 
use  Eup  to  create  an  index  series  which  picks  out  a  section  of  vector.  (Since  Evector  takes 
in  an  OSS  series  it  is  technically  a  transducer,  however,  it  is  on-line  and  is  an  enumerator 
m  spirit .  I 

(Evector  #(b  a  r)  (Eup  1  :to  2))  [a  r] 

(Evector  "BAR"  [0  2  1  1  4  l] )  =>  [#\B  #\R  #\A  #\A] 

The  value  returned  by  Evector  can  be  used  as  a  destination  for  alters. 

(let  ((v  "F00BAR")) 

(alterS  (Evector  v  (Eup  2  :to  4))  #\-)  v)  =>  "FQ - R" 

Esequence  sequence  ^optional  (indices  (Eup))  =>  elements 

The  function  Esequence  is  the  same  as  Evector  except  that  it  will  work  on  any  Com¬ 
mon  Lisp  sequence.  However,  since  it  has  to  determine  the  iype  of  sequence  at  run-time, 
it  is  much  less  efficient  than  either  Elist  or  Evector.  (The  value  returned  by  Esequence 
can  be  used  as  a  destination  for  alters.) 

(Esequence  ’(bar))  =>  [b  a  r] 

(Esequence  #(b  a  r))  =>  [bar] 

Ehash  table  =>  keys  values 

This  function  returns  two  OSS  series  containing  keys  and  their  associated  values.  The 
first  element  of  keys  is  the  key  of  the  first  entry,  the  first  element  of  values  is  the  value 
in  the  first  entry,  and  so  on.  (There  are  no  guarantees  as  to  the  order  in  which  entries 
will  be  enumerated.! 

(Ehash  (let  ((h  (make-hash-table) ) ) 

(setf  (gethash  ’color  h)  ’brown) 

(setf  (gethash  ’name  h)  ’fred) 

h))  =>  [color  name]  [brown  fred]  ; in  some  order 

In  the  pure  Common  Lisp  version  of  the  OSS  macro  package.  Ehash  is  rather  inefficient, 
because  Common  Lisp  does  not  provide  incremental  support  for  scanning  t  he  element s  of 
a  hash  table.  However,  in  the  Symbolics  Common  Lisp  version  of  the  OSS  macro  package. 
Ehash  is  quite  efficient. 

Esymbols  ftoptional  (package  *package*)  =>  symbols 

This  function  creates  an  OSS  series  of  the  symbols  in  package  (which  defaults  to  the 
current  package).  (  There  are  no  guarantees  as  to  the  order  in  which  symbols  will  be 
en  itinerated . ) 
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(Esymbols)  =>•  [foo  bar  baz  ...  zot]  ;  in  seme  order 

In  t lie  pure  Common  Lisp  version  of  the  OSS  macro  package,  Esymbols  is  rather 
inefficient,  because  Common  Lisp  does  not  provide  incremental  support  for  sc  anning  the 
symbols  in  a  package.  However,  in  the  Symbolics  Common  Lisp  version  of  the  oss  mac  r«> 
package.  Esymbols  is  quite  efficient. 

•  Efile  name  =>  items 

1  his  function  creates  an  OSS  series  of  the  items  written  in  the  tile  named  name.  1  C 
function  combines  the  functionality  of  sith-open-f lie  with  the-  action  <•!  reading  from 
the  file  (using  readl.  It  is  guaranteed  that  the  til*'  will  be1  closed  .  orrecth.  even  p  an 
error  occurs.  As  an  example  of  using  Efile.  assume  that  the  forms  (a),  (l  2).  and  T 
have  been  written  into  the  file  "test .  lisp". 

(Efile  "test. lisp")  =>  [(a)  (l  2)  T] 

e  EnumerateF  init  step  ioptional  test  =>  items 

The  higher-order  function  EnumerateF  is  used  to  creat  e  new  kinds  of  enumerators.  1  lie 
init  must  be  a  value  of  some  type  Ti.  The  step  argument  must  be-  a  non-OSS  function 
from  Tl  to  Tl.  The  test  argument  (if  present)  must  be  a  non-OSS  function  from  I  I  to 
boolean. 

Suppose  that  the  series  returned  by  EnumerateF  is  >.  1  lie  first  output  element  ><i  has 
the  value  50  =  init.  For  subsequent  elements.  5,  step(. s',  , ). 

If  the  test  is  present,  the  output  consists  of  elements  up  to.  but  not  including,  the 
first  element  for  which  test(S,)  is  true.  In  addition,  it  is  guaranteed  that  step  will  not  be 
applied  to  the  element  for  which  test  is  true.  If  there  is  no  test,  then  the  output  series 
will  be  of  unbounded  length.  (In  this  situation.  EnumerateF  is  not  an  early  terminator.) 

(EnumerateF  ’(abed)  #  ’  eddr  tt’null)  =>  [(a  bed)  (c  d)] 

(EnumerateF  ’(a  bed)  #’cddr)  =>  [(a  bed)  (c  d)  nil  nil  ...] 

(EnumerateF  list  ft’cdr  #’null)  rE  (Esublists  list) 

If  there  is  no  test,  then  each  time  an  element  is  output,  the  function  step  is  applied  to 
it.  Therefore,  it  is  important  that  other  factors  in  an  expression  cause  termination  before 
EnumerateF  computes  an  element  which  step  cannot  be  applied  to.  In  this  regard,  it  is 
interesting  that  the  following  equivalence  is  almost,  but  not  quite  true.  The  difference  is 
that  including  the  test  argument  in  the  call  on  EnumerateF  guarantees  that  step  will  not 
be  applied  to  the  element  which  fails  test,  while  the  expression  using  TuntilF  guarantees 
that  it  will. 

(TuntilF  test  (EnumerateF  init  step))  ^  (EnumerateF  init  step  test) 

•  Enumerate- inclusiveF  init  step  test  >  items 

I  he  higher-order  (unction  Enumerate-mclusiveF  ;«  the  ,ame  as  EnumerateF  except 
that  1 1 1 « ■  first  element  for  which  test  i -  true  is  included  m  t  he  out  put .  As  with  EnumerateF. 
it  is  guaranteed  that  step  will  not  be  applied  to  the  element  tor  which  test  i-  true. 

(Enumerate  inclusiveF  '(a  l>)  #’cddr  d’nulli  - [(a  b)  ()] 
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On-Line  Transducers 

Iransducers  compute  OSS  series  from  oss  series  and  form  the  heart  of  mo-t  oss 
''\;'r'--Mii[i-  This  section  and  the  next  one  present  the  predeiiued  t  raitsdm  er*  that  are 
on-line  (i.e..  all  of  their  inputs  and  outputs  are  on-line1.  These  transducers  are  singled 
out  because  they  can  be  used  more  flexibly  than  the  transducers  which  are  off  line.  In 
particular,  it  is  impossible  to  violate  the  off-line  port  isolation  restriction  without  using 
an  oif-line  t ransdurer. 

•  Tprevious  items  ^optional  (i/e/imli  nil)  (amount  1)  =c  s lufteditem - 

1  his  (unction  cn'ates  a  series  which  is  shitted  right  amount  elements.  The  input 
amount  must  be  a  positive  integer.  Ihe  shifting  is  done  by  inserting  amount  copies  of 
default  before  items  and  discarding  amount  elements  from  the  end  of  items.  The  outpu' 
is  always  the  same  length  as  the  input. 

(Tprevious  [a  b  c]  )  =>  [nil  a  b] 

(Tprevious  [a  b  c]  ’z)  [z  a  b] 

(Tprevious  [a  b  c]  ’z  2)  [z  z  a] 

(Tprevious  [])=>[] 

Ihe  word  previous  is  used  as  the  root  for  the  name  of  this  function,  because  the 
function  is  typically  used  to  acres*  previous  values  of  a  series.  An  example  of  Tprevious 
used  in  this  way  is  shown  in  conjunction  with  Tuntil  below. 

Io  insert  some  amount  of  stuff  in  front  of  a  *eries  without  losing  any  of  the  elements 
off  the  end.  use  Tconcatenate  a*  shown  below. 

(Tconcatenate  [z  z]  [a  b  c]  )  =>  [z  z  a  b  c] 

•  Tlatch  item s  ftkey  :after  ibefore  :pre  :post  masked-item* 

This  function  acts  like  a  latch  electronic  circuit  component.  Each  input  element 
causes  the  creation  of  a  corresponding  output  element.  After  a  specified  number  of  non- 
null  input  elements  have  been  encountered,  the  latch  is  triggered  and  the  output  mode 
is  permanently  changed. 

Ihe  :after  and  ibefore  arguments  specify  the  latch  point.  The  latch  point  is  just 
after  the  :after-th  non-null  '•lenient  in  item s  or  just  before  the  ibefore-th  non-null 
element.  If  neither  : after  nor  ibefore  is  specified,  an  : after  of  1  is  assumed.  If  both 
are  specified,  it  is  an  error. 

If  a  :pre  is  specified,  every  'dement  prior  to  the  latch  point  is  replaced  by  this  value. 
It  a  ipost  is  specified,  this  value  is  used  to  replace  every  element  after  the  latch  point. 
Il  neither  is  specified,  a  ipost  ■>(  nil  is  assumed. 


(Tlatch  [nil  c  nil  d  a]  )  [nil  c  nil  nil  nil] 

(Tlatch  [nil  c  nil  d  a]  ibefore  2  ipost  T)  [nil  c  nil  T  T] 

(Tlatch  [nil  c  nil  d  a]  ibefore  2  ipre  ’z)  =>  [z  z  z  d  e] 

As  a  more  realistic  example  >>l  using  Tlatch.  suppose  that  a  programmer  wants  to 
write  a  program  get-codes  which  takes  in  a  li*t  and  returns  a  list  of  all  of  the  numbers 
which  appear  in  the  list  after  the  second  number  in  the  list. 
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(defun  get-codes  (list) 

(lets  ((elements  (Elist  list))) 

(Rlist  (Tselect  (Hatch  (numberp  elements)  :  after  2  :  pre  nil) 
elements ) ) ) ) 

(get-codes  ’(a  b34cd5e6  f))  =>  (5  6) 

•  Tuntil  />•>(</'  items  =>  initial-items 

I  h i >  (unction  truncates  an  OSS  series  of  elements  based  on  an  OSS  series  of  boolean 
value.-.  I  lie  output  consists  of  all  of  the  elements  of  item-  up  to.  but  not  including,  the 
first  element  which  corresponds  to  a  non-null  element  of  boo/s.  1  hat  is  to  say.  if  the 
first  non-null  value  in  bools  is  the  mth.  the  output  will  consist  of  ail  of  the  elements  of 
items  up  to,  but  not  including,  the  mth.  (  1  he  effect  of  including  the  /nth  element  in 
the  output  can  be  obtained  by  using  Tprevious  as  shown  in  the  last  example  below.)  In 
addition,  the  output  terminates  as  soon  as  either  input  runs  out  of  elements  even  if  a 
non  null  element  of  bools  has  not  been  encountered. 

(Tuntil  [nil  nil  T  nil  T]  [12-34  -5])  ->  [l  2] 

(Tuntil  [nil  nil  T  nil  T]  [l] )  =>  [l] 

(Tuntil  (Eoss  :R  nil)  (Eup))  =>[012...] 

(Tuntil  [nil  nil  T  nil  T]  (Eup))  =>  [0  l] 

(lets  ((x  [1  2  -3  4  -5] )) 

(Tuntil  (minusp  x)  x))  =>  [l  2] 

(lets  ((x  [1  2  -3  4  -5]  )) 

(Tuntil  (Tprevious  (minusp  x))  x))  =>  [12  -3] 

If  the  items  input  of  Tuntil  is  such  that  it  can  be  used  as  a  destination  for  alters, 
then  the  output  of  Tuntil  can  be  used  as  a  destination  for  alters. 

(lets*  ((list  ’(a  b  10  c)) 

(x  (Elist  list)) 

(y  (Tuntil  (numberp  x)  x))) 

(alters  y  (list  y)) 
list)  =>  ((a)  (b)  10  c) 

•  TuntilF  preil  items  =>  initial-items 

I  lit-  function  i-  the  same  as  Tuntil  except  that  it  takes  a  functional  argument  instead 
of  an  nss  -cries  of  boolean  values.  The  non  OSS  function  pred  is  mapped  over  item'  in 
order  to  obtain  a  series  of  boolean  values.  I  Like  Tuntil.  TuntilF  is  can  fie  used  as  a 
destination  of  alters  it  items  can.)  1  he  basic  relationship  between  TuntilF  arid  Tuntil 
is  shown  in  the  last  example  below. 

(TuntilF  O’minusp  [12-3  4  -5])  =>  [l  2] 

(TuntilF  t’minusp  [l])  =>  [l] 

(TuntilF  i’minusp  (Eup))  =>  [0  1  2  ...] 

(TuntilF  pred  items) 

(lets  ((var  items))  (Tuntil  (TmapF  pred  var)  var)) 

Mn-  functii.n-  Tuntil  and  TuntilF  are  both  earl'  terminators.  This  can  sometimes 
ie.i  i  'ii  conflicts  with  the  restriction  that  within  each  on-line  subexpression,  there  must 
be  ,,  da'a  flow  path  from  each  termination  point  to  each  output,  lo  get  the  same  effect 
wr  fimit  u-mg  an  early  terminator  u-c  Tselect  of  Tlatch  a-  dioun  below 


(Tuntil  bools  items) 

=£  (Tselect  (not  (Hatch  bools  :post  T))  items) 

(TuntilF  #’pred  items'' 

~  (Tselect  (not  (Hatch  (pred  items)  :pcst  T))  items) 

TmapF  function  irest  items-list  =>  items 

l  he  higher-order  function  TmapF  is  used  to  create  simple  kinds  of  on-line  transducers. 
Its  arguments  are  a  single  function  and  zero  or  more  OSS  series.  The  function  argument 
must  he  a  non-OSS  tunetion  which  is  compatible  with  the  number  of  input  series  and  the 
types  of  their  elements. 

A  single  OSS  series  is  returned,  bach  element  of  this  series  is  the  result  of  applving 
function  to  the  corresponding  elements  of  the  input  series.  (  That  is  to  say.  if  TmapF  re 
ceives  a  single  input  series  R  it  will  return  a  single  out  put  5  such  that  5,  fnnctiunl  R.  I.  > 

I  he  length  ot  the  output  is  the  same  as  the  length  oi  the  shortest  input.  It  there  are 
no  bounded  series  inputs  (e.g..  i!  there  are  no  series  inputs),  then  TmapF  will  generate  an 
unbounded  OSS  series. 

(TmapF  #’+[12  3]  [4  5] )  =>  [5  7] 

(TmapF  #’sqrt  [])  =>  [] 

(TmapF  tt’gensyn)  =>  [#:G003  #:G004  #:G005  ...] 

TscanF  {init}  function  item s  =>  results 

I  he  higher-order  function  TscanF  is  used  to  create  complex  kinds  of  on-line  transduc¬ 
ers.  (1  he  name  is  borrowed  from  APL.)  The  init  argument  of  present)  must  be  a  non-OSS 
value  of  some  type  Tl.  The  function  argument  must  be  a  binary  non-OSS  function  from 

II  and  some  type  1 2  to  Tl.  The  items  argument  must  be  an  OSS  series  whose  elements 
are  of  type  12.  If  the  init  argument  is  not  present  than  Tl  must  equal  T 2. 

I  he  function  argument  is  used  to  compute  a  series  of  accumulator  values  of  type  Tl 
which  is  returned  as  the  output  of  TscanF.  The  output  is  the  same  length  as  the  series 
input  and  consists  of  the  successive  accumulator  values. 

Suppose  that  the  series  input  to  TscanF  is  R  and  the  output  is  S'.  The  basic  rela¬ 
tionship  between  the  output  and  the  input  is  that  S,  -  function[S,  \.R,).  If  the  init 
argument  is  specified,  it  is  used  as  an  initial  value  of  the  accumulator  and  the  first  output 
element  >'0  has  the  value  Sn  function!  init .  R0).  Typically,  but  not  necessarily,  init  is 
chosen  so  that  it  is  a  left  identity  of  function.  If  that  is  the  case,  then  50  R0.  It  is 

important  to  remember  that  the  elements  of  items  are  used  as  the  second  argument  of 
function.  1  he  order  of  arguments  is  chosen  to  highlight  this  fact. 

(TscanF  0  #’+  [l  2  3]  )  H-  [13  6] 

(TscanF  10  #’+  [l  2  3])  H  [ll  13  16] 

(TscanF  nil  #’cons  [a  bj)  =->  [(nil  .  a)  ((nil  .  a)  .  b)J 

(TscanF  nil  #’(lambda  (state  x)  (cons  x  state))  [a  b] )  =>•  [(a)  (b  a)] 

If  the  init  argument  is  not  specified,  then  the  first  element  of  the  output  is  computed 
different  I  \  from  the  succeeding  elements  and  50  R  0.  (If  function  is  cheap  to  evaluate. 
TscanF  run-  more  efficiently  if  it  is  provided  with  an  init  argument.)  One  situation  where 
one  typically  lorn  to  leave  out  'he  imt  argument  is  when  function  does  not  have  a  left 
identity  element  as  in  the  last  example  below. 
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I,  TscanF  **♦  [l  2  3])  =>  [l  3  6] 

(TscanF  #’max  [132])  =>  [133] 

Ait  interesting  example  ot  a  scanning  process  is  tin-  npi-rainm  of  piur,itnni.  In  tins 
process,  a  total  is  divided  up  and  allocated  between  ,t  nun, be'  categories.  |  he  alloca 
t  ion  is  done  based  on  percentages  which  are  associated  a  r  it  t  he  t  ategories .  ■  ho r  example, 
some  number  of  packages  might  be  divided  up  between  a  number  of  people,  i  One  might 
think  that  this  could  be  done  straightforwardly  by  multiplying  the  total  by  each  ot  the 
percentages.  I  nfort unately.  this  mapping  approach  does  not  work. 

1'he  proration  problem  is  more  complex  than  it  !:r.-!  appears,  1  vpicalh.  there  is  a 
limit  to  the  divisibility  of  the  total  ie.g..  when  a  group  ot  packages  is  divided  up.  the 
individual  packages  cannot  be  subdivided ).  1  his  mean-  that  rounding  must  be  performed 
each  time  the  total  is  multiplied  by  a  percentage.  In  addition,  it  is  usually  important 
that  the  total  be  allocated  exactly  i.e..  that  the  sum  <>l  the  ulloca’ions  be  exactly  equal 
to  the  total,  rather  than  being  one  more  or  one  lc".  s.  .mning  a  required  in  order  to 
make  sure  t hat  things  come  out  exactly  right. 

As  a  concrete  example  of  proration,  suppose  that  'ft  packages  need  to  be  allocated 
among  three  people  based  on  the  percentages  fV  1 .  IV'.  and  JO'..  Assuming  that  the 
percentages  and  the  number  of  packages  are  all  repre  en'ed  as  integers,  simple  mapping 
would  lead  to  the  incorrect  result  below  in  which  the  allocations  add  up  to  100  instead 
of  09. 

(prognS  (round  (/  (*  99  [35  45  20])  100) J)  [35  45  20] 

1  he  transducer  Tprorate  below  solves  the  prorat  ion  problem  by  using  TscanF.  It  takes 
in  a  total  and  an  OSS  series  of  percentages  and  return >  an  nss  series  of  allocations.  The 
basic  action  of  the  program  is  to  multiply  each  percentage  by  the  total.  However,  it 
also  keeps  track  of  how  much  of  the  total  has  been  allocated.  When  the  last  percentage 
is  encountered,  the  allocation  is  set  to  be  everything  which  remains  to  be  allocated. 
(This  can  cause  a  significant  distortion  in  the  final  allocation,  but  it  guarantees  that  the 
allocations  will  always  add  up  to  the  total  no  matter  what  has  happened  with  rounding 
along  the  way.)  In  order  to  determine  when  the  last  percentage  is  being  encountered,  the 
program  keeps  track  of  how  much  percentage  has  been  accounted  tor  and  assumes  that 
the  percentages  always  add  up  to  100. 

(defun  prorate-step  (state  percent) 

(let*  ((total  (second  state)) 

(unallocated  (third  state)) 

(unused-percent  (fourth  state)) 

(allocation  (if  (-  percent  unused-percent)  unallocated 
(round  (/  (*  total  percent)  100))))) 

(setf  (first  state)  allocation) 

(setf  (third  state)  (-  unallocated  allocation)) 

(setf  (fourth  state)  (-  unused-percent  percent)) 
state) ) 

(defunS  Tprorate  (total  percents) 

(declare  (type  oss  percents)) 

fear  (TscanF  (list  0  total  total  100)  #  'prorate  step  percents  ) ' ) 

(Tprorate  99  [35  45  20])  1-  [35  45  19] 
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An  interest  ins  aspect  of  t  lie  function  Tprorate  is  that  the  state  manipulated  by  the 
scanned  function  prorate-step  lias  four  parts:  an  allocation,  the  total,  the  unallocated 
portion  of  the  total,  and  the  remainin',!  percent  a  go  not  vet  allocated.  This  illustrates  the 
lad  that  TscanF  can  he  used  with  complex  state  objects.  I  1  he  same  is  t rue  of  EnumerateF 
and  ReduceF.I  However,  it  also  illustrates  that  accessing  the  various  parts  of  a  complex 
state  is  awkward  and  inefficient. 

fortunati  o.  it  is  often  possible  to  get  around  the  need  for  a  complex  state  object  by 
using  a  compound  oss  expression,  for  the  example  of  proration,  this  can  be  done  as 
shown  below.  Simple  mapping  is  combined  with  two  scans  which  keep  track  of  cumulative 
values.  \n  implicitly  mapped  test  is  used  to  make  sure  that  things  come  out  right  on 
the  last  step,  i  The  function  Tprevious  is  used  to  access  the  previous  value  of  the  series 
unallocated. ) 

(defunS  Tprorate-multi-state  (total  percents) 

(declare  (type  oss  percents)) 

(letS*  ((allocation  (round  (/  (*  percents  total)  100))) 

(unallocated  (TscanF  total  allocation)) 

(unused-percent  (TscanF  100  percents))) 

(if  (zerop  unused-percent) 

(Tprevious  unallocated  total) 
allocation) ) ) 


Cotruncation 

A  key  feature  of  every  on-line  transducer  is  that  it  terminates  as  soon  as  any  input 
runs  out  of  elements.  Put  another  way,  the  output  is  never  longer  than  the  shortest 
input.  (If  the  transducer  is  also  an  early  terminator,  tlmn  the  output  can  be  shorter  than 
the  shortest  input,  otherwise  it  must  be  the  same  length  as  the  shortest  input.)  This 
effect  is  referred  to  as  cotruncation,  because  it  acts  as  if  each  input  had  been  truncated 
to  the  length  of  the  shortest  input.  If  several  enumerators  and  on-line  transducers  are 
combined  together  into  an  OSS  expression,  cotruncation  will  typically  cause  all  of  the 
series  produced  by  the  enumerators  to  be  truncated  to  the  same  length.  For  example,  in 
the  expression  below,  all  of  the  series  (including  the  unbounded  series  produced  by  Eup) 
are  truncated  to  a  length  of  two. 

(Rlist  (*  (+  (Eup)  [4  5])  [12  3]))  =>  (4  12) 

Tcotruncate  items  4rest  more -items  =>  initial-items  irest  more-initial-items 

It  is  occasionally  important  to  specify  cotruncation  explicitly.  This  can  be  done  with 
t  lie  function  Tcotruncate  whose  only  action  is  to  force  all  of  the  outputs  to  he  of  the 
mine  length.  (If  anv  of  the  inputs  of  Tcotruncate  are  such  that  they  can  he  used  as 
destinations  of  alters,  then  the  corresponding  outputs  of  Tcotruncate  can  he  used  as 
<|est  mat  ions  < ,f  alters. ) 

(Tcotruncate  [l  2-3  4  -5]  [10]  )  [l]  [10] 

(Tcotruncate  (Eup)  [a  b]  )  "=>  [o  l]  [a  b] 

(Tcotruncate  [a  b]  [])  []  [] 
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An  important  feature  of  Tcotruncate  is  that  it  ha-  a  powerful  interaction  with  the 
requirement  that  within  each  on-line  subexpression,  there  must  he  a  data  flow  path  from 
each  termination  point  to  each  output.  Consider  the  function  weighted-squares-buggy 
below.  I  his  program  is  intended  to  take  a  vector  of  values  and  a  vector  of  weights 
and  return  a  list  of  two  vectors:  the  squares  of  the  values  and  the  squares  multiplied 
by  the  weights.  The  program  is  erroneous,  because  there  is  no  data  How  path  from 
(Evector  weight- vector)  to  (Rvector  squares). 

(defun  weighted-squares-buggy  (value- vector  '.eight-vector) 

(lets*  ((values  (Evector  value- vector ) )  ;Signals  error  18 

(weights  (Evector  weight- vector ) ) 

(squares  (*  values  values)) 

(weighted-squares  (*  squares  weights))) 

(list  (Rvector  squares)  (Rvector  weighted-squares)))) 

It  might  be  t  he  case  t hat  the  programmer  knows  t hat  value  -  vector  and  weight- vector 
always  have  the  same  length.  (Or  it  might  be  the  case  that  he  wants  both  output  values 
to  be  no  longer  than  the  shortest  input.)  In  either  case,  the  function  can  be  written 
as  shown  below.  The  key  difference  is  that  the  use  of  Tcotruncate  makes  both  out¬ 
puts  depend  on  both  inputs.  If  the  inputs  are  known  to  be  the  same  length,  the  use  of 
Tcotruncate  can  be  thought  of  as  a  declaration. 

(defun  weighted-squares  (value-vector  weight- vector) 

(lets*  (((values  weights) 

(Tcotruncate  (Evector  value-vector) 

(Evector  weight-vector))) 

(squares  (*  values  values)) 

(weighted-squares  (*  squares  weights))) 

(list  (Rvector  squares)  (Rvector  weighted-squares)))) 

(weighted-squares  #(1  2  3)  #( 3  2  1))  =>  (#(1  4  9)  #(3  8  9)) 

Off-Line  Transducers 

This  section  and  the  next  two  describe  transducers  that  are  not  on-line.  Most  of  these 
functions  have  some  inputs  or  outputs  which  are  on-line.  The  ports  which  are  on  line 
can  be  used  freely.  However,  the  off-line  ports  have  to  be  isolated  when  they  are  used. 
(For  ease  of  reference,  the  off-line  ports  all  begin  with  the  letter  code  “0".) 

•Tremove-duplicates  Oitcms  toptional  ( comparator  #’ eql)  items 

I  hi-  function  is  analogous  to  remove-duplicates.  It  creates  an  OSS  series  that  has  the 
same  elements  as  the  off-line  input  Otfrrns  with  all  duplicates  removed.  The  comparator 
is  used  to  determine  whether  or  not  two  items  are  duplicates.  If  two  items  are  the  same, 
then  the  item  which  is  later  iri  the  series  i-  discarded,  t  As  in  remove-duplicates  the 
algorithm  employed  is  not  particularly  efficient.  beii'g  f  >  f  r .  -  r . ;  iff  the  Oitcm s  input  of 
Tremove-duplicates  is  such  that  it  can  be  used  as  a  destination  for  alters,  then  the 
output  of  Tremove-duplicates  can  lie  used  as  a  destination  tor  alters.) 

(Tremove-duplicates  [l  2  1  ta)  (a)])  1  ft  T  (a)  (a)] 

(Tremove-duplicates  [121  (a)  (a)]  # ’equal!  >  [l  2  (a)] 


•  Tchunk  amount  ()i tents  =>  lists 

I  his  function  creates  an  OSS  series  ut  lists  of  length  amount  of  successive  Mibseries  of 
the  off-line  input  Oitems.  If  tin-  length  <>f  Oitems  i'  not  a  multiple  of  amount,  then  the 
last  (mod  (Rlength  O/fems)  amount)  elements  of  Oitenis  will  not  appear  in  any  output 
chunk. 

(Tchunk  2  [abode])  [(a  b)  (c  d)] 

(TchunJc  6  [abed])  =>  [] 

•  Twindow  amount  Oitems  =>  lists 

I  his  function  creates  an  OSS  series  of  lists  of  length  amount  of  subseries  of  the  off¬ 
line  input  Oiteins  starting  at  each  element  position.  If  the  length  of  Oitenis  is  less  than 
amount,  the  output  will  not  contain  any  windows.  The  last  example  below  shows  Twindow 
being  used  to  compute  a  moving  average. 

(Twindow  2  [abed])  =>  [(a  b)  (b  c)  (c  d)] 

(Twindow  4  [abed])  =>■  [(a  b  c  d)] 

(Twindow  6  [abed])  =>  [] 

(prognS  (/  (apply  #’+  (Twindow  2  [2468]))  2))  =>  [357] 

•  Tconcatenate  Oitemsl  Oitems'J  fcrest  more-Oitems  items 

This  function  creates  an  Oss  series  by  concatenating  together  two  or  more  off-line 
input  OSS  series.  The  length  of  the  output  is  the  sum  of  the  lengths  of  the  inputs.  (The 
elements  of  the  individual  input  series  are  not  computed  until  they  need  to  be.) 

(Tconcatenate  [b  c]  [J  [d] )  =>  [bed] 

(Tconcatenate  []  [] )  [] 

•  TconcatenateF  Enumerator  Oitenis  =>  items 

The  Enumerator  must  be  a  quoted  OSS  function  that  is  an  enumerator.  The  function 
TconcatenateF  applies  Enumerator  to  each  element  of  the  off-line  input  Oitems  and 
returns  the  series  obtained  by  concatenating  all  of  the  results  together.  If  Enumerator 
returns  multiple  values,  then  TconcatenateF  will  as  well. 

(TconcatenateF  tf’Elist  [(a  b)  ()  (c  d)])  =>  [abed] 

(TconcatenateF  #’Elist  [()  ()])  =>  [] 

(TconcatenateF  #’Eplist  [(a  1)  (b  2  c  3)])  =>  [a  b  c]  [12  3] 

•  Tsubseries  Oitems  start  ^optional  below  items 

This  function  creates  an  oss  series  containing  a  subseries  of  the  elements  of  the  off¬ 
line  input  Oitems  from  start  up  to,  but  not  including,  below.  If  below  is  greater  than  the 
length  of  Oitenis.  output  nevertheless  >tops  as  soon  as  the  input  runs  out  of  elements.  If 
below  is  not  specified,  the  output  continues  all  the  way  to  the  end  of  Oitems.  Both  of 
the  argument'  start  and  below  must  he  non-negative  integers. 

(Tsubseries  [abed]  1)  =>  [be  d] 

(Tsubseries  [abed]  13)  =>  [b  c] 

(Rlist  (Tsubseries  (Elist  list)  1  2))  =  (subseq  list  1  2) 
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If  the  Oitem s  input  of  Tsubseries  is  such  ilia!  it  can  he  used  as  a  destination  for 
alters,  then  the  output  of  Tsubseries  can  be  used  as  a  destination  for  alters. 

(let  ((list  ’(a  bed  e))) 

(alters  (Tsubseries  (Elist  list)  1  3)  (Eup)) 
list)  =>  (a  0  1  d  e) 

Ihe  function  Tsubseries  terminates  as  soon  as  it  has  written  t  he  last  out  put  element . 
As  a  result,  it  is  an  early  terminator.  I  his  can  sometimes  lead  to  conflicts  with  the 
restriction  that  within  each  on-line  subexpression,  there  must  he  a  data  flow  path  from 

'  each  termination  point  to  each  output,  lo  select  a  snideries  without  using  an  early 

terminator,  use  Tselect.  Tmask.  and  Eup  as  shown  below. 

(Tsubseries  Oitems  from  below) 

=  (Tselect  (Tmask  (Eup  from  : below  below))  Oitems) 

|  e  Tpositions  Ohools  =>  indices 

.  This  function  takes  in  an  OSS  series  and  returns  an  oss  series  of  the  indexes  of  the 

non-null  elements  in  the  off-line  input  series. 

I 

i  (Tpositions  [T  nil  T  44])  =>  [023] 

(Tpositions  [nil  nil  nil] )  =>  [] 

e  Tmask  Omonotonic-indices  bools 

;  I  his  function  is  a  quasi-inverse  of  Tpositions.  The  input  Omonotonic-indices  must 

be  a  strictly  increasing  OSS  series  of  non-negative  integers.  The  output,  which  is  al 

J  ways  unbounded,  contains  T  in  the  positions  specified  by  Omonotonic-indices  and  nil 

'  everywhere  else. 

;  (Tmask  [023])  =>  [T  nil  T  T  nil  nil  ..  ] 

■  (Tmask  [] )  =>  [nil  nil  ...] 

■  (Tmask  (Tpositions  x))  EE  (Tconcatenate  (not  (null  x))  (Eoss  :R  nil)) 

•  Tmerga  Oitems  1  Oitems'J  comparator  =>  items 

1  hi?  function  is  analogous  to  merge.  The  output  series  contains  the  elements  of  the 

two  off  line  input  series.  The  elements  of  Oitems l  appear  in  the  same  order  that  they 

are  rear!  in.  Similarly,  the  elements  of  Oifems2  appear  in  the  same  order  that  they  are 
read  in.  However  the  elements  from  the  two  inputs  are  intermixed  under  the  control  of 
•  he  comparator.  At  each  step,  the  comparator  is  used  to  compare  the  current  elements 
in  the  two  series.  If  the  comparator  returns  non  null,  the  current  element  is  removed 
trom  f)itenisl  and  transferred  to  the  output.  Otherwise,  the  next  output  comes  from 
Oitems'J.  flf.  as  in  the  first  example  below,  the  elements  of  the  individual  input  series 
are  ordered  with  respect  to  comparator,  then  the  remit  will  also  he  ordered  with  respect 
to  comparator.  II.  as  in  the  second  example  below,  either  input  is  not  ordered,  the  result 
vv  ill  not  he  ordered.  ) 

(Tmerge  [1  3  7  9]  [4  S  8]  »’<)  --S-  [1  3  4  5  7  8  9] 

(Tmerge  [17  3  9]  [4  5  8]  •’<>  “l-  [1  4  5  7  3  8  9] 

(Tmerga  x  y  #’(lambda  tx  y)  T >  )  ■_  (Tconcatenate  x  y) 


> 
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•  Tlastp  (Stems  =>  hool-  item - 

1  his  function  takes  in  a  series  ami  returns  a  -erie.-  of  boolean  values  having  the  same 
length  such  that  the  last  value  Is  T  ami  all  ot  the  other  values  are  nil.  If  the  input  series 
is  unbounded,  then  the  output  '-'ties  will  also  be  unbounded  and  evert  element  of  the 
out  put  will  be  nil. 

It  turns  out  t  hat  this  output  cannot  be  computed  by  an  on-line  OSS  function.  There¬ 
fore.  it  Tlastp  returned  only  the  boolean  values  described  above,  the  isolation  restrictions 
would  make  it  impossible  to  use  the  input  series  and  the  output  values  together  in  the 
same  computation.  In  order  to  get  around  this  problem.  Tlastp  returns  a  second  out 
put  which  is  identical  to  the  input.  I  his  output  can  he  used  in  lieu  of  tie  input  in 
combination  with  the  boolean  values. 

(Tlastp  [abed])  =>  [nil  nil  nil  T]  [a  b  c  d] 

(Tlastp  [a] )  =>  [T]  [a] 

(Tlastp  []  )  =>  []  [] 

(Tlastp  (Eup))  [nil  nil  nil  ...]  [012  ...] 

As  an  example  of  using  Tlastp.  it  is  interesting  to  return  to  the  example  of  proration 
discussed  in  conjunction  with  the  function  TscanF.  Both  of  the  proration  functions  pre 
seated  earlier  assume  that  the  percentages  always  add  up  to  100.  If  this  turns  out  not 
to  be  the  case,  then  an  exact  allocation  of  t  lie  total  is  not  guaranteed.  Tin-  following 
program  ensures  that  exact  allocation  will  occur  no  mutter  what  the  percentages  add  up 
to.  It  does  this  by  using  Tlastp  to  detect  which  percentage  is  the  last  one. 

(defunS  Tprorate-robust  (total  Opercents) 

(declare  (type  oss  Opercents)) 

(lets*  (((is-last  percents)  (Tlastp  Opercents)) 

(allocation  (round  (/  (*  percents  total)  100))) 

(unallocated  (TscanF  total  allocation))) 

(if  is-last  (Tprevxous  unallocated  total)  allocation))) 

(Tprorate-robust  99  [35  45  20] )  =>  [35  45  19] 

(Tprorate-robust  99  [35  45  21] )  =>  [35  45  19] 

(Tprorate  99  [35  45  21])  [35  45  21] 

Selection  and  Expansion 

Selection  and  its  inverse  are  particularly  important  kinds  of  off-line  transducers. 

•  Tselect  bools  toptional  item -  Oiteui- 

I  his  function  selects  element-  from  a  series  ba-ed  on  a  boolean  series.  I  he  off-line 
output  consists  of  the  element-  o|  items  whn  h  correspond  to  non-null  elements  of  bools. 

I  hat  i-  to  say.  the  nth  element  o|  item-  j-  m  the  output  iff  the  nth  element  of  bools  is 
non  null.  I  he  order  ol  the  element-  Hi  Oitenis  I-  the  -ante  a s  the  order  of  the  elements 
ill  item'.  I  he  output  terminate-  a-  -oon  as  either  input  run-  out  of  elements.  It  m> 
items  input  i-  specified,  then  the  non  null  element-  of  bools  are  l  hem-elves  returned  as 
the  output  ol  Tselect.  iff  the  items  input  of  Tselect  i-  such  that  it  can  be  used  as 
a  destination  lor  alters,  then  tin  output  ol  Tselect  can  lie  used  as  a  destination  lor 
alters. ! 


:to 


(Tselect  [T  nil  T  nil]  [abed])  >  [a  c] 
(Tselect  [a  nil  b  nil] )  =>  [a  b] 

(Tselect  [nil  nil]  [a  b] )  [] 
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An  interesting  aspect  of  Tselect  is  that  the  out  put  sene-,  is  off  line  rat  her  t  han  having 
the  two  input  series  be  off-line.  This  is  done  in  recognition  of  the  fact  that  the  two  input 
series  are  always  in  synchrony  with  each  other.  Having  only  one  port  which  is  off- line 
allows  more  flexibility  then  having  two  ports  which  are  off  line. 

One  might  want  to  select  elements  out  of  a  series  based  on  t  heir  positions  in  the  series 
rather  than  on  boolean  values.  This  can  be  done  straight forwardlv  using  Tmask  as  shown 
below . 

(Tselect  (Tmask  [02])  [a  b  c  d] )  =>  [a  c] 

(Tselect  (not  (Tmask  [0  2]))  (Eup  10))  [ll  13  14  15  ..] 

A  final  feature  of  Tselect  in  particular,  and  off-line  ports  in  general,  is  illustrated  by 
the  program  below.  In  this  program,  the  Tselect  causes  the  first  Elist  to  get  out  of 
phase  with  the  second  Elist.  As  a  result,  it  is  important  to  think  of  oss  expressions  as 
passing  around  series  objects  rather  than  as  merely  being  abbreviations  for  loops  where 
things  are  always  happening  in  lock  step.  The  latter  point  of  view  might  lead  to  the  idea 
that  the  output  of  the  program  below  would  be  ((a  1)  (c  2)  (d  4)). 

(letS  ((tag  (Elist  ’(a  bed  e))) 

(x  (Elist  ’(1  -224  -5)))) 

(Rlist  (list  tag  (Tselect  (plusp  x)  x))))  =>  ((a  1)  (b  2)  (c  4)) 

•  TselectF  pred  Oitrms  =>■  items 

fliis  function  is  the  same  as  Tselect.  except  that  it  maps  the  non-OSS  function  pred 
over  Oitnif  '<>  obtain  a  series  of  boolean  values  with  which  to  control  the  selection.  In 
addition.  TselectF  has  an  off-line  input  rather  than  an  off-line  output  (this  is  fractionally 
more  efficient  I.  d  he  logical  relationship  between  Tselect  and  TselectF  is  shown  in  the 
la.-t  example  below. 

(TselectF  k’identity  [a  nil  nil  b  nil])  =>  [a  b] 

(TselectF  H’plusp  [-1  2-34])  =>  [2  4] 

(TselectF  pred  items) 

r1  (lets  ((var  items))  (Tselect  (TmapF  pred  var)  var)) 

e  Texpand  boo/.-  Oitrms  ^optional  (default  nil)  =>  items 

[hi-  function  is  a  quasi  inverse  of  Tselect.  (The  name  is  borrowed  from  API.)  The 
output  contains  the  elements  of  Oitrms  spread  out  into  the  positions  specified  by  the 
non-null  elements  in  boo/s  i.e..  the  nth  element  of  Oitrms  is  in  the  position  occupied 
bv  the  /i'll  non  null  element  in  boob.  I  he  other  positions  in  the  output  are  occupied  by 
d'T.iu/f.  the  output  stops  ,is  soon  as  hunts  runs  out  of  elements,  or  a  non  null  element 
iii  feeds  i-  encountered  for  which  there  is  no  corresponding  element  in  Oitrms. 

(Texpand  [nil  T  nil  T  T]  [a  b  c]  )  =>  [nil  a  nil  b  c] 

(Texpand  [nil  T  nil  T  T]  [a] )  [nil  a  nil] 

(Texpand  [nil  T]  [a  b  c]  ’ z)  [z  a] 

(Texpand  [nil  T  nil  T  T]  []  )  >  [nil] 
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Splitting 

An  operation  whirl]  is  closely  related  to  selection,  i'  splitting.  In  selection,  specified 
elements  arc  selected  out  of  a  series.  It  is  not  possible  to  apply  blither  operations  to  t  In- 
elements  which  are  not  selected,  because  they  have  been  discarded.  In  contrast,  splitting 
divides  up  a  series  into  two  or  more  parts  which  can  be  individually  used.  Both  Tsplit 
and  TsplitF  have  on-line  inputs  and  off-line  outputs.  The  outputs  have  to  be  off-line, 
because  they  are  inherently  non-'V  nchronized  with  each  other. 

Tsplit  ifenis  bools  fcrest  more- funds  =>  Oitrmsl  Oitrins'2  ftrest  morr-Oitcms 

This  function  takes  in  a  series  of  elements  and  partitions  them  between  two  or  more 
outputs.  If  there  are  n  boolean  inputs  then  there  are  n  ■  1  outputs.  Kach  input  element 
is  placed  in  exactly  one  output  series.  Suppose  that  the  nth  element  of  bools  is  non-null. 
In  this  case,  i  ue  nth  element  of  items  will  be  placed  in  Oitrmsl.  On  the  other  hand,  if 
the  nth  element  of  bools  is  nil.  the  second  boolean  input  I  il  any)  is  consulted  in  order  to 
see  whether  the  input  element  should  be  placed  in  the  second  output  or  in  a  later  output. 
[  A  s  in  a  cond.  each  time  a  boolean  element  is  nil.  the  next  boolean  series  is  consulted.) 
If  the  nth  element  of  every  boolean  series  is  nil.  then  the  nth  element  of  itt'ius  i*  placed 
in  the  last  output. 

(Tsplit  [-1  -2  34]  [T  T  nil  nil])  =>  [-1  -2]  [3  4] 

(Tsplit  [-1  -2  3  4]  [T  T  nil  nil]  [nil  T  nil  T]  )  ■=>  [-1  -2]  [4]  [3] 

(Tsplit  [-1  -2  3  4]  [T  T  T  T]  )  =>  [-1  -2  3  4]  [] 

It  the  items  input  of  Tsplit  is  such  that  it  can  be  used  as  a  destination  for  alters, 

then  all  of  the  outputs  of  Tsplit  can  be  used  as  destinations  for  alters. 

(letS*  ((list  ’(-1  2  -3)) 

(x  (Elist  list)) 

((x+  x-)  (Tsplit  x  (plusp  x)))) 

(alters  x+  (  +  x+  10)) 

(alters  x-  (-  x-  10)) 
list)  =>  (-11  12  -13) 

TsplitF  items  prerf  Strest  rnore  /ired  Oitrmsl  Oitems‘2  ftrest  more-Oifem* 

Ibis  function  is  the  same  as  Tsplit.  except  that  it  takes  predicates  as  arguments 
rather  than  boolean  series.  I  he  predicates  must  be  non-OSS  functions  and  are  applied  to 
items  in  order  to  create  boolean  values.  I  he  relationship  between  TsplitF  and  Tsplit  is 
almost  but  riot  exactly  as  shown  below. 

(TsplitF  items  predl  pred2) 

(lets  ((var  items)) 

(Tsplit  var  (TmapF  prodl  var)  (TmapF  pred2  var))) 

I  li<’  reason  that  the  equivalence  above  does  not  quite  hold  is  that,  as  in  a  cond.  the 
predicates  an-  not  applied  to  individual  elements  of  it”ms  unless  the  resulting  value  is 
needed  in  order  to  determine  which  output  series  the  element  should  be  placed  in  (e.g.. 
if  the  tirst  predii  ate  returns  mm  null  when  given  the  nth  element  of  items,  the  second 
predicate  will  not  be  railed  i.  Md*  promotes  efficiency  ami  allows  earlier  predicates  to 
act  as  guard-  lor  later  predicate*. 
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(TsplitF  [-1  -2  3  4]  # ’minusp)  =t>  [-1  -2]  [3  4] 

(TsplitF  [-1  -2  3  4]  #’minusp  #’evenp)  [-1  -2]  [4]  [3] 


Reducers 

Reducers  produce  non-OSS  outputs  based  on  OSS  inputs.  There  are  two  basic  kinds 
of  reducers:  ones  that  combine  the  elements  of  OSS  series  together  into  aggregate  data 
structures  (e.g..  into  a  list)  and  ones  that  compute  some  summary  value  fro  in  these 
elements  (e.g.,  the  sum).  All  the  predefined  reducers  are  on-line.  A  few  reducers  are  also 
early  terminators.  These  reducers  are  described  in  the  next  section. 

•  Rlist  items  =>  list 

This  function  creates  a  list  of  the  elements  in  items  in  order. 

(Rlist  [a  b  c] )  =S>  (a  b  c) 

(Rlist  [] )  =>  () 

(Rlist  (fn  (Elist  x)  (Elist  y)))  EE  (mapcar  #’fn  x  y) 

(Rlist  (fn  (Esublists  x)  (Esublists  y)))  EE  (maplist  #’fn  x  y) 

•  Rbag  item.'  =>  list 

litis  function  creates  a  list  of  the  elements  in  items  with  no  guarantees  as  to  the  order 
of  the  elements.  The  function  Rbag  is  more  efficient  than  Rlist. 

(Rbag  [a  b  c]  )  =>  (cab)  ;in  some  order 
(Rbag  [] )  =>  () 

•  Rappend  lists  =>  list 

t  his  function  creates  a  list  by  appending  the  elements  of  lists  together  in  order. 

(Rappend  [(a  b)  nil  (c  d)])  (abed) 

(Rappend  []  )  =>  () 

•  Rnconc  lists  list 

This  function  creates  a  list  by  nconcing  the  elements  of  lists  together  in  order.  The 
function  Rnconc  is  faster  than  Rappend,  but  modifies  the  lists  in  the  OSS  series  lists. 

(Rnconc  [(a  b)  nil  (c  d)] )  =>  (abed) 

(Rnconc  [])  =>  () 

(let  ((x  ’(a  b)))  (Rnconc  (Eoss  x  x)))  =>  (a  b  a  b  a  b  ...) 

(Rnconc  (fn  (Elist  x)  (Elist  y)))  EE  (mapean  #’fn  x  y) 

(Rnconc  (fn  (Esublists  x)  (Esublists  y)))  EE  (mapeon  #’fn  x  y) 


•  Ralist  keys  values  alist 

I  tii'  film  tion  creates  an  alist  containing  keys  and  values.  It  terminates  a*  soon  as 
either  of  t  tie  inputs  runs  out  of  elements.  Tf  t  here  are  duplicate  keys,  t  hey  will  be  [Hit  on 
the  a  I  i '  t .  tint  order  is  preserved. 
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(Ralist  [a  b]  [12])  >  ((a  .  1)  (b  .  2)) 

(Ralist  [a  b]  [])=>() 

(Ralist  keys  values)  ~  (Rlist  (cons  keys  values)) 

Rplist  indicators  values  plist 

This  function  creates  a  plist  containing  keys  and  values.  It  terminates  as  soon  as 
either  ot  the  inputs  runs  out  of  elements.  If  there  are  duplicate  indicators,  they  will  he 
put  on  the  plist.  but  order  is  preserved. 

(Rplist  [aba]  [l  2  3]  )  =>  (a  1  b  2  a  3) 

(Rplist  [a  b]  [])=>() 

(Rplist  keys  values)  EE  (Rnconc  (list  keys  values)) 

Rhash  keys  values  4rest  option-plist  =>  table 

This  function  creates  a  hash  table  containing  keys  and  values.  It  terminates  as  soon 
as  either  of  the  inputs  runs  out  ot  elements.  The  option-plist  can  contain  any  options 
acceptable  to  make-hash-table.  1  he  option-plist  cannot  refer  to  variables  bound  by  lets. 

(Rhash  [color  name]  [brown  fred] )  =>  #<hash-table  23764432> 

;;hash  table  containing  color->brown,  name->fred 

(Rhash  [cclor  name]  [] )  =>  #<hash-table  23764464> 

;; empty  hash  table 

Rvector  items  &  key  :size  irest  option-plist  vector 

This  function  creates  a  vector  containing  the  elements  of  items  in  order.  The  option- 
plist  can  contain  any  options  acceptable  to  make-array.  The  option-plist  cannot  refer  to 
variables  bound  by  lets. 

The  function  Rvector  operates  in  one  of  two  ways.  If  the  :size  argument  is  supplied, 
then  Rvector  assumes  that  items  will  contain  exactly  :size  elements.  A  vector  is  created 
of  length  :size  with  the  options  specified  in  option-plist  and  the  elements  of  items  are 
stored  in  it.  (If  items  has  fewer  than  :size  elements,  some  of  the  slots  in  the  vector  will 
be  left  in  their  initial  state.  If  items  has  more  than  :size  elements,  an  error  will  ensue.) 
In  this  mode,  Rvector  is  very  efficient,  but  rather  inflexible. 

(Rvector  [1  2  3]  :size  3)  =>  #(1  2  3) 

(Rvector  [#\B  #\A  #\R]  :size  3  .-element-type  ’string-char)  =>  "BAR" 
(Rvector  [l]  :size  4  : initial-element  0)  =>  #(1  000) 

If  the  :size  argument  is  not  supplied,  then  Rvector  allows  for  the  creation  of  an 
arbitrarily  large  vector.  It  does  this  by  using  vector-push-extend.  In  order  for  this  to 
work,  it  forces  .-adjustable  to  be  T  and  : fill-pointer  to  be  0  no  matter  what  is  specified 
in  the  options  list.  In  this  mode,  an  arbitrary  number  of  input  elements  can  be  handled, 
however,  things  are  much  less  efficient,  since  the  vector  created  is  not  a  simple  vector. 

(Rvector  [l  2  3])  =>  tt(l  2  3) 

(Rvector  []  )  =>  #( ) 

(Rvector  [#\B  #\ A  #\R]  : element-type  ’string-char)  =>  "BAR" 

lo  store  a  series  in  a  preexisting  vector,  use  alters  of  Evector. 
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(let  ((v  #(a  b  c) ) ) 

(alters  (Evector  v)  (Eoss  1  2)) 
v)  =>  #(l  2  c) 

•  Rfile  name  item s  irest  option-plist  T 

This  function  creates  a  file  named  name  and  writes  the  elements  of  items  into  it 
using  print.  The  option-plist  can  contain  any  of  the  options  accepted  by  open  except 
direction  which  is  forced  to  be  :output.  All  of  the  ordinary  printer  control  variables 
are  obeyed  during  the  printout.  The  value  T  is  always  returned.  The  option  plist  cannot 
refer  to  variables  bound  by  lets. 

(Rfile  "test. lisp"  [’(a)  ’(1  2)  T]  :if-exists  :append)  T 
; ;The  output  " 

; ;  (a) 

; ;  (1  2) 

; ;T  "  is  printed  into  the  file  "test. lisp". 

•  Rlast  items  ^optional  ( default  nil)  =>  item 

This  function  returns  the  last  element  of  items.  If  items  is  of  zero  length,  default  is 
returned. 

(.Rlast  [a  b  c] )  c 
(Rlast  []  ’z)  z 

•  Rlength  items  =>  number 

This  function  returns  the  number  of  elements  in  items. 

(Rlength  [a  b  c] )  3 

(Rlength  [] )  =>  0 

•  Rsum  numbers  =>  number 

This  function  computes  the  sum  of  the  elements  in  numbers.  These  elements  must 
be  numbers,  but  they  need  not  be  integers. 

(Rsum  [12  3])  6 

(Rsum  [] )  =>  0 

(Rsum  [1.1  1.2  1.3])  3.6 

•  Rmax  numbers  =>  number 

1  his  function  computes  the  maximum  of  the  elements  in  numbers.  These  element- 
must  be  non-complex  numbers,  but  they  need  not  be  integers.  The  value  nil  is  returned 
it  number -  has  length  zero. 

(Rmax  [2143])  =>  4 

(Rmax  [] )  =>  nil 

(Rmax  [1.2  1.1  1.4  1.3])  =>  1.4 

•  Rmin  number -  >  number 

I  hi-  function  computes  the  minimum  of  the  elements  in  number -.  I  hese  elements 
must  be  non  complex  numbers,  but  they  need  not  be  integers.  The  value  nil  is  returned 
if  nu tuber-  has  length  zero. 
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(Ruin  [2143])  E-  1 

(Rmin  []  )  — •  nil 

(Rmin  [1.2  1.1  1.4  1.3])  -  1.1 

•  ReduceF  in i t  function  item >■  =>  result 

I  hi-  In  net  ion  is  analogous  to  reduce.  In  addition,  it  is  similar  to  TscanF  except  that 
ini  t  is  not  optional  and  the  final  value  of  tin-  accumulator  is  t  ho  only  value  returned  as 
shown  in  the  last  example  below.  It  items  is  of  length  zero,  init  is  returned.  As  with 
TscanF.  function  must  be  a  non  uss  lunrtion  and  the  value  of  init  i-  typically  chosen  to 
be  a  left  identity  of  function.  It  i-  important  to  remember  that  the  elements  <d  item >  are 
used  as  the  second  argument  ol  function.  I  he  order  of  arguments  i>  chosen  to  highlit;!,- 
this  fact. 

(ReduceF  0  #’+  [123])  ^>6 
(ReduceF  0  #’+[])=>  0 
(ReduceF  0  #’+  x)  EE  (Rsum  x) 

(ReduceF  init  function  items) 

=  (letS  ((var  init)) 

(Rlast  (TscanF  var  function  items)  var)) 

In  order  to  do  reduction  without  an  initial  seed  value,  use  Rlast  of  TscanF.  Note  that 
although  a  seed  value  does  not  have  to  be  specified,  a  value  to  be  re;  timed  U  ther,  an¬ 
no  elements  in  items  still  has  to  be  specified. 

(Rlast  (TscanF  #’ max  x)  nil)  IE  (Rmax  x) 


Early  Reducers 

The  following  four  reducers  are  early  terminators.  Kach  of  these  functions  has  a  non- 
early  variant  denoted  by  the  suffix  "-late".  The  early  variants  are  more  efficient,  because 
they  terminate  as  soon  as  they  have  determined  a  result.  This  may  be  long  before  any 
of  the  input  series  run  out  of  elements.  However,  as  discussed  at  the  end  of  this  section, 
one  has  to  be  somewhat  careful  when  using  an  early  reducer  in  an  OSS  expression. 

•  Rfirst  items  ftoptional  (default  nil)  ->  item 

•  Rfirst-late  items  ftoptional  (default  nil)  =>  item 

Both  of  these  function-,  return  the  fir>t  element  of  items.  If  items  is  of  zero  length. 
default  is  returned.  The  only  difference  between  the  functions  is  that  Rfirst  stops  im¬ 
mediately  after  reading  the  first  element  of  items,  while  Rfirst-late  does  not  terminate 
until  items  runs  out  of  element  -. 

(Rfirst  [a  b  c]  )  — v  a 
(Rfirst  []  ’z)  ;_i  z 

•  Rnth  n  items  ftoptional  ( default  nil)  item 

•  Rnth-late  n  items  ftoptional  (default  nil)  item 

Both  of  these  functions  return  the  nth  element  of  items.  If  n  is  greater  than  or  equal 
t . ,  t h*-  length  .it  items,  default  i-  returned,  l  lic  only  difference  between  the  functions 
i-  that  Rnth  stops  immediately  ,t ft «-r  reading  the  nth  element  of  items,  while  Rnth-late 
does  nil!  terminate  until  items  run-  out  <>f  elemen 
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i  Rnth  1  [a  b  c]  )  b 
vRnth  1  []  ’z)  =>  z 


•  Rand  boo/ -  /><>,-/ 

•  Rand- late  booty-  bool 

Both  of  tli  e-e  tune  i  ions  com  put  e  the  and  <  >  t  t  lie  eieuien !  -  in  o  oo/-.  \  s  with  'he  t  unet  i<  >u 
and.  nil  l-  returned  it  any  element  <>t  booty  is  nil.  O;  herw i-e  'he  last  element  of  hoot.'  i- 
returned.  I  he  value  T  is  returned  it  bools  ha-  length  zero.  1  lie  • » : il \  ditlerence  Between 
'he  tun-'hoii-  i-  that  Rand  terminates  as  soon  as  a  nil  is  encountered  m  the  input,  while 
Rand-late  does  not  terminate  until  booty  runs  out  ot  elements. 

(Rand  [a  b  c]  )  =>  c 
(Rand  [a  nil  c]  )  =>  nil 
(Rand  [] )  ^>  T 

(Rand  (pred  (Esequence  x)  (Esequence  y)))  ~  (every  3’pred  x  y) 

•  Ror  booty  =>  bool 

•  Ror-late  booh  =>  Irool 

Both  ot  these  functions  compute  the  or  of  the  elements  in  booh.  As  with  the  function 
or.  nil  is  ret  urned  if  every  element  of  bools  is  nil.  Ot  herwise  t  he  first  non-null  element  of 
booty  is  returned.  I  he  value  nil  is  returned  it  booty  lias  length  zero.  The  only  difference 
Between  the  functions  is  that  Ror  terminates  as  soon  as  a  non- null  value  is  encountered 
:ri  the  input,  while  Ror-late  does  not  terminate  until  bools  runs  out  of  elements. 

(Ror  [a  b  c] )  a 
(Ror  [a  nil  c] )  =>  a 
(Ror  []  )  =>  nil 

Ror  (pred  (Esequence  x)  (Esequence  y)))  =  (some  tt’pred  x  y) 

Care  must  be  taken  when  using  early  reducers.  As  discussed  in  the  section 
on  restrictions.  OSS  expressions  are  required  to  obey  the  restriction  that  within  each  on¬ 
line  subexpression,  there  must  be  a  data  flow  path  from  each  termination  point  to  each 
outpu*.  Karly  reducers  interact  with  this  restriction  since  early  reducers  are  termination 
point-.  As  a  result,  there  must  be  a  data  flow  path  from  each  early  reducer  to  each 
output  of  the  containing  on-line  subexpression. 

Since  reducers  compute  non-OSS  values,  they  directly  compute  output-  of  on-line 
subexpressions.  As  a  result,  it  is  impossible  for  there  to  be  a  data  flow  path  from  a 
reducer  to  any  output  other  than  the  output  the  reducer  it-eif  computes.  1  hep-fore,  it 
i-  not  possible  to  use  an  early  reducer  unless  that  reducer  compute-  the  only  output  of 
the  on-line  subexpression. 

I' or  example,  consider  the  following  four  expres-n >n 1  he  hr-'  t  no  expre.--i.ui-  return 
the  -ante  p's  til  t .  However,  the  first  i-  more  efficient.  I  hi-  >-  a  ;  >  r<  ■  t  <  >t  \  p  1 1  a  1  example  of  a 
situation  here  it  is  better  to  use  an  early  redueer.  In  contrast,  the  la.-t  two  expre--ion- 
do  not  produce  the  same  results.  1  he  next  to  hi-t  expre--i.»n  i-  erroneous  hei.ause  there 
i-  no  data  flow  path  from  the  instance  of  Rf  irst  to  the  -ecu  id  out  put .  I  o  compute  the-e 
two  outputs,  a  non-early  reducer  must  b<  u-<d  a-  in  tie-  L-i  example 


(lets  ( (x  (Elist  ’(1  2-345-6-7  8)))) 

(Rfirst  (TselectF  tt’nunusp  k)))  ->  -3 

(lets  ( (x  (Elist  '(12-345  6  7  8)'m 

(Rfirst-late  (TselectF  S’nunusp  x)))  3 

(letS  ((x  (Elist  ’(l  2-345-6-7  8))))  ;Signals  error  18 
(valS  (Rfirst  (TselectF  O’minusp  x)) 

(Rsum  x) ) ) 

(lets  ((x  (Elist  ’(1  2-345-6-7  8)))) 

(valS  (Rfirst-late  (TselectF  ff’minusp  x)) 

(Rsum  x)))  -3  4 

Series  Variables 

1  he  principal  way  to  create  OSS  variables  is  to  use  the  form  lets,  i  I  hese  variables 
are  also  created  by  the  forms  lambdas  and  defunS.) 

•  lets  car- value- pair-list  {decl}*  ftbody  expr-hst  =>  result 

The  form  lets  is  syntactically  analogous  to  let.  Just  as  in  a  let.  the  first  subform 
is  a  list  of  variable- value  pairs.  I  he  lets  form  defines  the  scope  of  these  variables  and 
gives  them  the  indicated  values.  As  in  a  let.  one  or  more  declarations  can  follow  the 
variable- value  pairs.  These  can  be  used  to  specify  the  types  of  the  variables. 

The  variables  created  by  lets  can  be  OSS  variables  or  non-OSS  variables.  Which  are 
which  is  determined  by  the  type  of  the  value  that  is  bound  to  the  variable.  As  in  let. 
the  variables  are  bound  in  parallel.  In  the  example  below,  y  is  an  OSS  variable  while  x 
and  z  are  non-OSS  variables. 

(lets  ((x  ’(1  2  3)) 

(y  (Elist  ’(1  2  3))) 

(z  (Rsum  (Elist  ’(1  2  3))))) 

(list  x  (Rmax  y)  z))  =>  ((1  2  3)  3  6) 

Cnlike  let,  lets  does  not  support  degenerate  variable- value  pairs  which  consist  solely 
of  a  variable.  (Since  lets  variables  cannot  be  assigned  to.  see  below,  degenerate  pairs 
would  be  of  little  value.  I 

(letS  (x)  ...)  ;Signals  error  9 

1  he  following  example  illustrates  the  use  of  a  declaration  in  a  letS.  Declarations  are 
handled  in  the  same  way  that  they  are  handled  in  a  let. 

(lets  ( (x  (Elist  ’(1  2  3)))) 

^declare  (type  integer  x)) 

( Rsum  x ) )  6 

The  form  lets  goes  beyond  let  to  include  the  functionality  of  multiple- value-bind. 
\  variable  in  a  variable- value  pair  can  be  a  list  of  variables  instead  of  a  single  variable. 
When  tin-  is  the  case,  the  variables  pick  up  the  first,  second,  etc.  results  returned  by  the 
value  expression.  Ilf  there  is  only  one  variable,  it  get'  the  first  value.  II  nil  is  used  in 
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lieu  of  a  variable,  the  corresponding  value  i-  ignored.  .  ||  there  arc  tewer  variable-  -li.u 
values,  the  extra  values  are  ignored.  I  [dike  multiple- value-bind.  lets  -ignal-  an  ero  r  i‘ 
there  are  more  variables  than  values,  i  Note  that  there  i>  n<>  form  multiple- value-bindS 
and  that  the  form  multiple-value-bind  <  annol  be  used  m-ide  nt  ui  oss  expression 
bind  the  results  of  an  OSS  function.  I 

(lets  (((key  value)  (Ealist  ’((a  .  l)  (b  .  2')))) 

(Rlist  (list  key  value)))  =>  ((a  1)  (b  2 ' ) 

(lets  ((key  (Ealist  ’((a  .  1)  (b  .  2))))) 

(Rlist  key) )  =>  (a  b) 

(letS  (((nil  value)  (Ealist  ’((a  .  if  (b  .  I  ■  i  1 )  ) 

(Rlist  value))  =>  (l  2) 

(letS  (((key  value  x)  (Ealist  ’((a  .  1)  (,b  .  2)J))) 

(Rlist  (list  key  value  x ) ) )  ;Signals  error  8 

The  cxpr-list  of  a  lets  has  the  effect  of  grouping  -e\er-d  oss  expressions  together. 
1  he  value  of  the  last  form  in  the  e.vpr  h>t  is  ret urned  as  'he  \ alue  ot  t he  letS.  I  his  value 
may  be  an  oss  value  or  a  non-OSS  value 

In  addition  to  placing  all  of  the  expressions  in  the  -aiue  lets  binding  scope,  the 
grouping  imposed  by  the  expr  list  causes  the  entire  body  to  become  an  OSS  expression. 
This  can  alter  the  way  implicit  mapping  is  applied  by  including  non-oss  functions  in  the 
OSS  expression. 

The  restricted  nature  of  OSS  variables.  There  are  a  number  of  ways  in  which 
the  variables  bound  by  letS  for  lambdaS  and  def unS  i  are  more  restricted  than  the  ones 
bound  by  let.  For  the  most  part,  these  restrictions  stem  from  the  fart  that  when  the  oss 
macro  package  transforms  an  oss  expression  into  a  loop,  it  rearranges  the  expression- 
extensively.  1  his  forces  letS  variable  scopes  to  be  supported  by  variable  renaming  rather 
than  binding.  One  result  ot  this  i-  that  it  i-  not  po--ihle  to  declare  (or  proclaim*  a 
letS  variable  to  be  special,  f  Standard  Common  I.i.-p  doe-  not  provide  any  method  for 
determining  whether  or  not  a  variable  has  been  proclaimed  special.  As  a  result.  the 
OSS  macro  paikagc  is  unable  to  issue  an  error  message  when  a  special  lets  variable  is 
encountered,  f  he  Symbolics  Common  l.isp  version  of  the  oss  macro  package  does  issue 
an  error  message. ) 

(proclaim  ’(special  z)) 

(letS  ((z  (Elist  ’  ( 1  2  3))))  (Rsum  z))  ; erroneous  expression 

Another  limitation  is  that  programmer-  are  not  allowed  to  assign  value.-  to  letS 
variable-  in  the  body  of  a  letS.  i  I  hi-  restriction  apphe-  whether  or  not  the  variable- 
con  t  ain  OSS  values.  |  1  he  only  t  i me  lets  varta  Ides  ran  be  giv  ui  a  value  is  t  he  moment  t  hex 
are  bound,  i  Although  assignment  could  be  supported  easily  enough,  the  rearrangement- 
introduced  by  the  oss  macro  package  would  make  it  \er\  «>uifusing  tor  a  programmer 
to  figure  out  exactly  what  would  happen  in  a  given  ..i  ..I'mn.  In  particular,  nan  •!> 
apply  in  g  implicit  mapping  to  setq  would  lead  to  pe<  u  liar  re  -  u  It  - .  In  addition,  outlawing 
assignment.'  enhances  the  functional  nature  of  the  oss  macro  package,  i  An  error  message 
is  issued  whenever  sui  fi  an  assign  men  i  i-  attempted 


'•erie-  \  .tn,ihlr s 


:w 


i  lets  (.  ( x  (Elist  ’(1  2  3)))) 

(setq  x  (1+  x))  jSignals  error  12 

(Rlist  x)) 

aspect  ut  lets  variables  is  that  their  scope  is  somewhat  limited.  In  partic¬ 
ular.  lets  variables  can  he  referenced  in  a  lets  or  mapS  which  is  inside  the  lets  which 
binds  them.  However,  they  cannot  be  referenced  in  lambda  or  lambdaS.  (As  above,  this 
limitation  is  imposed  in  order  to  avoid  contusions  due  to  rearrangements.  Further,  it  is 
not  obvious  what  it  would  mean  to  reter  to  an  OSS  variable  in  a  lambda.  Should  some 
sort  ot  implicit  mapping  be  applied )  No  attempt  is  made  to  issue  error  messages  in  t his 
situation.  Bather.  the  variable  reference  in  question  is  merely  treated  as  a  free  variable. 

(lot  ( ( x  4)) 

(lots  ((x  (Elist  ’(1  2  3)))) 

(Rlist  (TmapF  #’(lambda  (y)  (+  x  y))  x))))  =>  (567) 

•  lets*  i  i r  value  pair-li.<t  {decl}*  fcbody  expr-list  =>  result 

I" he  form  letS*  is  exactly  the  sanm  as  lets  except  that  the  variables  ate  bound 
sequentially  instead  of  in  parallel. 

(lets*  ((x  ’(l  2  3)) 

(y  (Elist  x)) 

(z  (Rsum  y) ) ) 

(list  x  (Rmax  y)  z))  =>  ((l  2  3)  3  6) 

•  prognS  ftbody  expr-list  result 

(  •  As  shown  below.  prognS  is  identical  to  lets  except  that,  it  cannot  contain  any  variable- 

value  pairs  or  declarations.  It  is  a  degenerate  form  whose  only  function  is  to  delineate  an 
OSS  expression.  This  can  alter  the  way  implicit  mapping  is  applied  by  including  non-OSS 
functions  in  the  OSS  expression. 

(prognS  .  expr-list)  =  (lets  ()  .  expr-list) 

Complete  OSS  expressions  do  not  return  OSS  values.  A  key  point  relevant 
to  the  discussion  above  is  that  syntactically  complete  OSS  expressions  are  not  allowed 
to  return  oss  values.  This  is  relevant,  because  lets  and  prognS  are  often  used  in  such 
a  way  that  an  oss  series  gratuitously  ends  up  as  the  return  value.  For  example,  the 
main  intent  ot  the  expression  below  i-  to  print  out  the  elements  of  the  list.  However,  as 
written,  the  expression  appear-  to  ret  irn  an  oss  series  of  the  values  produced  by  prinl. 
Because  expression-  like  the  one  I  ehc.v  are  relatively  common,  it  was  decided  not  to  issue 
an  error  message  m  thi-  -ituatiot'  Kather.  the  oss  value  is  simply  discarded  and  no 
'.  alue  i  -  re>  a  rued . 

(prognS  (print  (Elist  ’(l  2))))  > 

;;The  output  "12"  is  printed. 

It  might  be  the  case  that  the  programmer  actually  desires  to  have  a  physical  series 
returned  in  the  example  above.  I  his  can  be  done  bv  using  a  reducer  such  as  Rlist  or 
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Rvector  as  show  n  below. 


(prognS  (Rlist  (prinl  (Elist  ’(l  2)))))  ->  (l  2) 

;  ;The  output  "12"  is  printed. 

Preventing  complete  OSS  expressions  from  returning  nss  values  does  not  limit  vvliat 
can  be  written,  because  programmers  can  always  return  a  non-oss  series.  This  can  be 
a  bit  cumbersome  at  times,  but  it  is  highly  preferable  to  the  large  inefficiencies  which 
would  be  introduced  by  automatically  constructing  physical  representations  for  oss  series 
in  situations  where  the  returned  values  are  not  used  in  further  computation. 

Coercion  of  Non-Series  to  Series 

If  an  OSS  input  of  an  OSS  function  is  applied  to  a  non-series  value,  the  type  conflict  is 
resolved  by  converting  the  non-OSS  value  into  a  series  by  inserting  Eoss.  That  is  to  say. 
a  non-OSS  value  acts  the  same  as  an  unbounded  OSS  series  of  the  value. 

(Ralist  (Elist  ’(a  b))  (*  23)) 

=  (Ralist  (Elist  ’(a  b))  (Eoss  :R  (*  2  3)))  =>  ((a  .  6)  (b  .  6)) 

l  sing  Eoss  to  coerce  a  non-OSS  value  to  an  OSS  series  has  the  effect  of  only  evaluating 
the  expression  which  computes  the  value  once.  This  has  many  advantages  with  regard  to 
efficiency,  but  may  not  always  be  what  is  desired.  Multiple  evaluation  can  be  specified 
by  using  TmapF  or  mapS. 

(Ralist  (Elist  ’(a  b))  (gensym))  =>  ((a  .  #:G004)  (b  .  #:G004)) 

(Ralist  (Elist  ’(a  b))  (TmapF  tt’gensym))  ((a  .  #:G004)  (b  .  #:G005)) 

Implicit  Mapping 

Mapping  operations  can  be  created  by  using  TmapF.  However,  in  the  interest  of  conve¬ 
nience.  two  other  ways  of  creating  mapping  operations  are  supported.  The  most  promi¬ 
nent  of  these  is  implicit  mapping.  If  a  non-OSS  function  appears  in  an  OSS  expression  and 
is  applied  to  one  or  more  arguments  which  are  OSS  series,  the  type  conflict  is  resolved  by 
automatically  mapping  the  function  over  these  series. 

(Rsum  (car  (Elist  ’((1)  (2))))) 

EE  (Rsum  (TmapF  #’car  (Elist  ’((l)  (2)))))  3 

(Rsum  (*  2  (Elist  ’(1  2)))) 

EE  (Rsum  (TmapF  #’(lambda  (x)  (*  2  x))  (Elist  ’(l  21)))  =>  6 

A>  shown  in  the  second  example,  implicit  mapping  actually  applies  to  I'ntire  imn- 
OSS  subexpressions  rather  than  merely  to  individual  functions.  This  promotes  efficiency 
and  makes  sure  that  related  groups  of  functions  are  mapped  together.  However,  it  is 
rmt  always  what  is  desired.  For  instance,  in  the  first  example  below,  the  call  mi  gensym 
gets  mapped  iri  conjunction  with  the  call  on  list.  This  causes  each  list  to  contain  a 
separate  gensym  variable.  It  might  be  the  case  that  the  programmer  wants  to  have  the 
same  gensym  variable  in  each  list.  This  can  be  .■•efiieved  bv  inserting  an  Eoss  as  shown  in 
the  second  example.  (Inserting  a  Eoss  here  and  there  ran  promote  eflicienev  by  avoiding 
unnecessary  recomputation  ) 
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(Rlist  (list  (Elist  ’(a  b))  (gensym))) 

EE  (Rlist  (TmapF  #’ (lambda  (x)  (list  x  (gensym))) 

(Elist  ’(a  b)^)  ->  (fa  #:G002'>  (b  #:G003)) 

(Rlist  (list  (Elist  ’(a  b))  (Eoss  :R  (gensym)))) 

EE  (Rlist  (TmapF  (f’list 

(Elist  ’ (a  b) ) 

(Eoss  : R  (gensym))))  ((a  #:G002)  'b  #:G002)) 

In  order  to  be  implicitly  mapped,  a  non oss  function  must  appear  inside  of  an  oss 
expression.  For  example,  the  instance  of  prinl  in  the  first  example  below  does  not  get 
implicitly  mapped,  because  it  is  not  in  an  oss  expression.  Implicit  mapping  of  the  print 
can  be  forced  by  using  prognS  as  shown  in  the  second  example  above. 

(prinl  (Elist  ’(1  2)))  =>  nil 

;;The  output  "NIL"  is  printed. 

(prognS  (prinl  (Elist  ’(1  2))))  => 

; ;The  output  "12"  is  printed. 

(  T he  result  of  the  first  example  above  is  that  NIL  gets  printed.  This  happens  because 
(Elist  ’(1  2  3))  is  a  syntactically  complete  OSS  expression  and  is  therefore  not  allowed 
to  return  a  series.  It  returns  no  values  instead.  The  function  prinl  demands  a  value 
anyway,  and  gets  nil.) 

Another  aspect  of  implicit  mapping  is  that  a  non-OSS  function  will  not  be  mapped 
unless  it  is  applied  to  a  series.  This  is  usually,  but  not  always,  what  is  desired.  C’onsider 
the  first  expression  below.  The  instance  of  prinl  is  mapped  over  x.  However,  the  instance 
of  princ  is  not  applied  to  a  series  and  is  therefore  not  mapped.  If  the  programmer  intends 
to  print  a  dash  after  each  number,  he  has  to  do  something  in  order  to  get  the  princ  to 
be  mapped.  This  could  be  done  using  TmapF  or  mapS.  However,  the  best  thing  to  do  is 
to  group  the  two  printing  statements  into  a  single  subexpression  as  shown  in  either  of 
the  last  two  examples  below.  This  grouping  shows  the  relationship  between  the  printing 
operations  and  causes  them  to  be  mapped  together. 

(lets  ((x  (Elist  ’(1  2  3)))) 

(prinl  x) 

(princ  "-"))  =>  "-" 

; ;The  output  "123-"  is  printed. 

(lets  ( (x  (Elist  ’(1  2  3)))) 

(progn  (prinl  x)  (princ  "-")))  -=> 

; ;The  output  "1-2-3-"  is  printed. 

(lets  ((x  (Elist  ’(1  2  3)))) 

(format  T  "*A-"  x))  => 

; ;The  output  "1-2-3-"  is  printed 

Ugly  details.  Implicit  mapping  is  easy  to  understand  when  applied  in  simple  situa¬ 
tions  such  as  the  ones  above.  However,  it  can  be  applied  to  any  Lisp  form.  I  hinds  become 
somewhat  more  complicated  when  control  constructs  (e.g..  if)  and  binding  construct' 
(e.g..  let)  are  encountered.  1  he  example  below  shows  the  implicit  mapping  of  an  if. 
I  his  creates  a  lambda  expression  containing  a  conditional  which  is  mapped  over  a  series. 
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A  key  t  hum  to  notice  in  thin  example  is  that  implicit  n..tj>pim!>  ot  if  i-  very  iiiHer<‘nt  from 
a  use  ot  Tselect.  In  particular,  t  lie  mapped  if  returns  a  \  ai  ue  corre>pondi  ng  t<>  even 
input,  while  the  Tselect  does  not. 

(Rlist  (if  (plusp  (Elist  ’(10  -11  12)))  (Eupl)) 

EE  (Rlist  (TmapF  i’dambda  (x  y)  (if  (plusp  x)  y  >  ' 

(Elist  ’(10  -11  12))  (Eup)))  (0  nil  2) 

(Rlist  (Tselect  (plusp  (Elist  ’(10  -11  12)1)  (Eup;))  >  (0  2) 

\nother  aspect  of  the  way  conditionals  are  hamlb-ii  noide  an  oss  expression  i- 
illustrated  below.  When  an  OSS  expre-simi  is  being  proeessed  m  order  t>>  <letermine  what 
should  be  implicitly  mapped,  the  expression  is  broken  up  into  uss  pieces  and  rum  oss 
pieces.  If  the  argument  of  a  conditional  is  an  oss  expression.  '  his  argument  will  end  up 
in  a  separate  piece  from  the  conditional  itself.  One  result  of  t  bis  is  tri.it  the  argument  will 
always  be  evaluated  and  the  conditional  will  therelore  lose  its  power  to  control  when  the 
argument  should  be  evaluated.  This  effect  will  happen  even  if.  as  m  the  example  below, 
the  conditional  does  not  have  to  be  mapped,  l  he  three  examples  below  all  produce  the 
same  value,  but  the  first  two  always  evaluate  (Rlist  (abs  (Elist  x)))  while  the  last 
may  not. 

(prognS  (if  (Ror  (minusp  (Elist  x))) 

(Rlist  (abs  (Elist  x))) 
x) ) 

EE  (prognS  (funcall  #’ (lambda  (y  z)  (if  y  z  x)) 

(Ror  (minusp  (Elist  x))> 

(Rlist  (abs  (Elist  x  ) ) ) ) ) 

2  (if  (Rot  (minusp  (Elist  x))) 

(Rlist  (abs  (Elist  x))) 
x) 

The  following  example  shows  the  implicit  mapping  ot  a  let.  'Among  other  things. 
fhis  illustrates  that  such  expressions  are  tar  from  clear.  In  general  it  is  belter  to  use  lets 
a>  in  the  second  example,  i 

(Rlist  (let  ((double  (*  2  (Elist  * ( 1  2))));  (*  double  double))) 

EE  (Rlist  (TmapF  •’ (lambda  (x) 

(let  ((double  (*  2  x)))  (*  double  double))) 

(Elist  ’(1  2))))  rr>  (4  16) 

(lets  ((double  (*  2  (Elist  ’(l  2))))) 

(Rlist  ( *  double  double)))  =>  (4  16) 

A  problem  with  the  implicit  mapping  of  a  let  lor  other  binding  forms '  i-  that  tin 
implicit  mapping  transformation  potentially  mmo  subexpressions  out  of  the  scope  of  t  he 
binding  torm  in  question.  This  can  change  the  meaning  <>!  the  expression  if  any  of  these 
subexpressions  contain  an  instance  of  a  variable  bound  in  t  lm  binding  form,  for  in  st  a  rice, 
in  the  example  above,  the  transformation  moves  the  subexpression  (Elist  ’(1  2))  <>ut 
of  the  scope  of  the  let.  This  would  cause  a  problem  d  this  subexpression  referred  to  t  in¬ 
variable  double. 
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In  order  to  a  void  till-  i  >  r  <  *  I  »!•  •  1 1 1 .  an  it  r<  >r  message  is  i"iiod  w  In -hit  it  i  in  |>l  hi  t  napping  « >  1 

a  l>i  mil  n  a  tiirm  causes  a  van  a  hie  reference  In  innvc  mit  i  il  a  |i  i  r  n  i  that  I  a  i;  i !  -  !  .  \\  hone\  »t 

ft  occ  i|r*.  'h's  problem  *  a  it  In*  die.  ia  led  h\  )  *»  *■  S  -in-  ■  r;  .ihuii' 

A  final  complexity  involves  !i •  r 1 1 1 ^  1 1 k •  ■  return,  return-f  roir.  throw.  etc.  I  !ii--f  * ■ . r 1 1 i ~ 

are  implicit lv  mapped  like  any  other  imn  Oss  form.  \\  hen  t  >,  a, a  >  \ a ! ua  1  «■<! .  t  i . < ■  \  will 
can  'i‘  an  exit,  i  I IIWCVIT.  1  !l  t*  limp  j »  Ti  a  I  me<  1  |i  \  till-  <  >s  s  ;  a*  :  i  ■  <  i  i  •  •  ■  in  1 1  <  i  m  1  a  1 1 1  .1  1  m  u  n  i  i  a  r  \ 
which  is  recognized  by  any  ol  the  e  fi  »r  t  :  i  -  1 1  .  a. .  it  (Ini'-  not  rria  t  a  prog  nr  c  a  t  ■:  h  >  \  •  a 

result .  ^iicli  a  in  mu  da  ry  uiu>t  lie  def  lin'd  w  h  ■<  h  will  mt\  >■  it'  r«*f«T»-m  .•  p.  an ' .  \  n  d  ie  ■ 
in  say.  tin-  hual  result'  * > t  the  ( > > ^  express a,  will  nut  in-  eninpiiteil  il  'he  expression  i« 
exited  in  this  way. 

Nested  loops.  Implicit  mapping  is  applied  when  '.i.nnss  t  i  i "  <  '  i . » 1 1  ^  r<  •  •  i .  <  m- 
values.  However,  implicit  mapping  n  not  applied  when  os-'  functions  ;eeeive  oss  v,d  .os. 
even  it  these  values  are  passed  in  mai  (iss  input-  \s  illustrated  In'lmv.  wiieneo-:  1  hi' 
situation  occurs,  an  error  message  i>  t-s'ied 

(Elist  (Elist  ’((1  2)  (3  4))')  ;Signals  error  M 

There  are  situation'  corresponding  to  nested  loop'  where  il  would  he  i e.«  -or.alile  to 
implicitly  map  subexpressions  containing  oss  tunction-.  lor  •  xample.  -me  : fit  write 
the  following  expression  in  order  to  copy  a  li't  of  lists. 

(Rlist  (Rlist  (Elist  (Elist  ’((1  2)  (3  4))))))  jSignals  error  14 

(Rlist  (TmapF  #’(lambda  (x)  (Rlist  (Elist  x')) 

(Elist  ’((1  2)  (3  4)))))  =>  l(l  2)  (3  4)) 

.Nevertheless,  expressions  like  the  first  one  above  ire  forbidden.  This  is  done  for 
two  reasons,  first,  in  more  complex  situation-  oss  expressions  corresponding  to  nested 
loops  become  so  contusing  that  sinii  expression'  are  very  hard  to  understand.  As  a 
result,  they  are  not  very  useful.  Second,  experience  suggests  that  a  large  proportion  ot 
situations  where  mapping  of  OSS  functions  might  be  done  arise  from  programming  errors 
rather  than  an  intention  to  have  a  nested  loop.  Outlawing  these  expression'  makes  it 
possible  to  find  these  errors  more  quickly. 

I  [lie  following  example  'hows  that  there  is  no  problem  with  having  one  loop  com 
piitation  following  another.  1  here  are  tin  t  vpe  confliet  in  tie-  situation  am!  no  implicit 
mapping  is  required.  ■ 

(Rsum  (Evector  (Rvector  (Elist  ’(1  21))))  3 
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Needless  to  say.  it  would  he  tin  reasonable  it  t  here  were  u<>  wav  to  write  oss  expressions 
corresponding  to  nested  loops,  first  of  all.  tins  <  an  a  I  w  a  \  -  !>••  done  using  TmapF  as  show  n 
atiove.  [ lowe\ er .  tins  <  an  he  rather  euin hersome.  [o  alleviate  'In  ddfieuity.  an  idditional 
lortn  ( mapS  i  i'  in’rodmed  wlu<h  l.n  dilates  the  expression  .>1  -e--ied  ••■mputati  ms. 


•  mapS  Jtbody  expr  ii.'t  item s 

I  he  e\pr  list  I  oil  s|  sis  ol  one  or  more  exp  res  'lolls.  |  hose  <-\pros'|oiis  are  1  reeled  as  t  tie 

itody  ol  a  lu  net  i<m  and  ma  pped  over  any  tree  oss  \  aria  hie-  w  h  ieh  appear  in  them.  1  hat 
is  to  say.  t  ii  e  first  oh-mon*  of  the  output  is  computed  by  evaluating  tin  expressions  m  an 
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<•11  vironment  where  each  oss  variable  is  bound  to  tin-  I i r > t  element  of  the  <  < >r r < j >< . n < i 1 1 1 u1 
-eries.  I  he  second  element  ol  t  he  out  put  i s  computed  by  e\  aluat  ing  t  lie  expressions  in  an 
environment  where  each  OSS  variable  is  bound  to  t  he  second  element  of  the  corresponding 
series,  etc.  The  way  mapS  could  be  used  to  copy  a  list  of -lists  is  shown  below.  A  lets  has 
to  be  used,  because  mapS  requires  that  the  series  being  mapped  over  must  be  held  in  a 
variable. 

(lets  ((z  (Elist  ’((1  2)  (3  4))))) 

(Rlist  (mapS  (Rlist  (Elist  z))))) 

=  (lets  ((z  (Elist  ’(Cl  2)  (3  4))))) 

(Rlist  (TmapF  #’ (lambda  (x) 

(Rlist  (Elist  x)))  z)))  ((1  2)  (3  4)) 

(Rlist 

(mapS 

(Rlist  (Elist  (Elist  ’((1  2)  (3  4)))))))  ;Signals  error  14 

Implicit  mapping  is  very  valuable.  From  the  above,  it  can  be  seen  that  although 
implicit  mapping  is  simple  in  simple  sit  nations,  there  are  a  number  of  situations  where  it 
becomes  quite  complex.  There  is  no  question  that  these  complexities  dilute  the  value  of 
implicit  mapping.  Nevertheless,  experience  suggests  that  implicit  mapping  is  so  valuable 
that,  warts  and  all.  it  is  perhaps  the  most  useful  single  feature  of  OSS  expressions. 

Literal  Series  Functions 

.lust  as  it  is  very  convenient  to  be  able  to  specify  a  literal  non-OSS  function  using 
lambda,  it  is  sometimes  convenient  to  be  able  to  specify  a  literal  OSS  function. 

•  lambdas  var-list  { Reel}*  *body  expr-list 

l  he  form  lambdaS  is  analogous  to  lambda  except  that  some  of  the  arguments  can  have 
oss  series  passed  to  them  and  the  return  value  can  be  an  OSS  series.  The  var-list  is 
simpler  than  the  lambda  lists  which  are  supported  by  lambda.  In  particular,  the  var-list 
must  consist  solely  of  variable  names  It  cannot  contain  any  of  the  lambda  list  keywords 
such  as  toptional  and  treat.  As  in  a  lets,  the  variables  in  the  var-list  cannot  be  assigned 
to  in  the  expr-list  or  referenced  inside  of  a  nested  lambda  or  lambdaS. 

As  in  a  lambda,  the  body  can  begin  with  one  or  more  declarations.  All  of  the  argu¬ 
ments  which  are  to  receive  OSS  values  have  to  be  declared  inside  the  lambdaS  using  the 
declaration  type  oss  (see  below).  All  of  the  other  arguments  are  assumed  to  correspond 
to  non  OSS  values,  .fust  as  in  a  lets,  the  declarations  may  contain  other  kinds  of  decla¬ 
rations  besides  type  oss  declarations.  However,  the  variables  in  the  var-list  cannot  be 
declared  (or  proclaimed)  to  be  special. 

1  he  expr-list  is  a  list  of  expressions  which  are  grouped  together  into  an  oss  expres 
-ion  as  in  a  lets  or  prognS.  The  value  of  the  function  specified  by  a  lambdaS  is  the  value 
of  the  last  form  iri  the  expr-list.  This  value  mayor  may  not  be  an  oss  series. 

In  many  ways.  lambdaS  bears  the  same  relationship  to  lets  that  lambda  bears  to  let. 
However,  there  is  one  key  difference.  The  expr-list  in  a  lambdaS  cannot  refer  to  anv 
tree  variables  *  huh  are  bound  by  a  lets.  defunS.  or  another  lambdaS.  Kuch  lambdaS  is 
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processed  in  complete  isolation  Irotii  the  oss  expression  which  surrounds  it.  The  only 
salues  which  can  enter  or  leave  a  lambdas  are  specified  by  the  var-list  and  non-oss 
variables  which  are  bound  outside  of  the  entire  containing  os«  expression. 

Another  key  feature  of  lambdas  is  that  the  only  place  where  it  can  validly  appear  is  as 
the  quoted  first  argument  of  funcallS  (see  below),  or  as  an  argument  to  a  macro  which 
will  eventually  expand  in  such  a  way  that  the  lambdas  will  end  up  as  the  quoted  first 
argument  of  a  funcallS. 

I  he  following  example  illustrates  the  use  of  lambdas.  It  shows  an  anonymous  OSS 
function  identical  to  Rsum. 

(funcallS  #’  ClambdaS  (.x) 

(declare  (type  oss  x)) 

(ReduceF  0  #’+  x)) 

(Elist  ’(1  2  3)))  =s  6 


•  type  oss  trest  variable-list 

This  type  declaration  can  only  be  used  inside  of  a  declare  inside  of  a  lambdas  or  a 
defunS.  It  specifies  that  the  variables  carry  OSS  values. 

•  funcallS  function  trest  expr-list  =>  r<  suit 

This  is  analogous  to  funcall  except  that  function  can  be  an  OSS  function.  In  partic¬ 
ular.  it  can  be  the  quoted  name  of  a  series  function,  a  quoted  lambdas,  or  a  macro  call 
which  expands  into  either  of  the  above.  It  is  also  possible  for  function  to  be  a  non-oss 
function,  in  which  case  funcallS  is  identical  to  TmapF.  If  function  is  an  expression  which 
evaluates  to  a  function  (as  opposed  to  a  literal  function),  then  it  is  assumed  to  be  a 
non-oss  function. 

(funcallS  # ’Elist  ’(1  2))  =  (Elist  >(1  2))  =>  [l  2] 

(funcallS  #’(lambdaS  (y)  (declare  (type  oss  y))  (*  2  y)) 

(Elist  ’(1  2)))  =>  [2  4] 

(funcallS  # ’ car  [(l)  (2)])  =>  [l  2] 

(funcallS  # ’ car  ’(1  2))  =>  Cl  1  1  1  ...] 

1  he  number  of  expressions  in  expr-list  must  be  exactly  the  same  as  the  number  of 
arguments  expected  by  function.  If  not.  an  error  message  is  issued.  In  addition,  the 
types  of  values  (either  oss  series  or  not )  returned  by  the  expressions  should  be  the  same 
as  the  types  which  are  expected  by  function.  If  not.  coercion  of  non- series  to  series  will 
he  applied  if  possible  in  order  to  resolve  the  conflict. 

Defining  Series  Functions 

\n  important  aspect  of  the  oss  macro  package  is  that  it  makes  it  easy  for  program¬ 
mers  to  define  new  oss  function-.  Straightforward  OSS  functions  can  be  defined  using 
i  he  facilities  outlined  below.  More  complex  oss  functions  can  be  defined  using  the  sub- 
prnnitive  facilities  described  m  (i  . 
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•  defunS  name  lambda  list  {doc}  {dec!}*  ftbody  expr  /i-f 

r hit.  is  analogous  to  defun,  but  for  OSS  function.-.  At  a  simple  level.  defunS  i-  ju-t 
syntactic  -ugar  which  defines  a  macro  that  create*-  a  funcallS  of  a  lambdas.  The  lambda 
list,  declarations,  and  expression  list  are  restricted  in  exactly  the  same  way  a-  in  a 
lambdaS  except  that  the  standard  lambda  list  keyword-  Aoptionai  and  ftkey  are  allowed 
in  the  lambda-list . 

(defunS  Rlast  (items  ^optional  (default  nil)) 

"Returns  the  last  element  of  an  OSS  series" 

(declare  (type  oss  items)) 

(ReduceF  default  #’ (lambda  (state  x)  x)  items)) 

EE  (defmacro  Rlast  (items  ftoptional  (default  'nil)) 

"Returns  the  last  element  of  an  OSS  series" 

‘(funcallS  #’ (lambdaS  (items  default) 

(declare  (type  oss  items)) 

(ReduceF  default  #’ (lambda  (state  x)  x)  items)) 
.items  .default)) 

However,  at  a  deeper  level,  there  is  a  key  additional  aspect  to  defunS.  Preprocessing 
and  checking  of  the  resulting  lambdaS  is  performed  when  the  defunS  is  evaluated  (or 
compiled),  rather  than  when  the  resulting  OSS  function  i-  used.  This  saves  time  when 
the  function  is  used.  More  importantly,  it  leads  to  better  error  messages  becau.-e  error 
messages  can  be  issued  when  the  defunS  is  initially  encountered,  rather  than  when  the 
oss  function  defined  is  used. 

Although  the  lambda  list  keyword-  ftoptional  and  ftkey  art*  supported  by  defunS.  it 
,-hould  be  realized  that  they  are  supported  in  the  way  they  are  supported  by  macros,  not 
the  way  they  are  supported  by  functions.  In  particular,  when  keywords  are  used  in  a  call 
on  t  he  oss  fund  ion  being  defined,  t  hey  have  to  be  literal  key  words  rather  t  hail  computed 
by  an  expression.  In  addition,  initialization  forms  cannot  refer  to  the  run-time  values  of 
other  arguments,  because  these  are  not  available  at  macro-expansion-time.  They  are  also 
not  allowed  to  refer  to  the  macro-expansion-time  value-  of  the  other  arguments.  They 
must  stand  by  themselves  when  computing  a  value.  A  quote  i-  inserted  so  that  this  value 
will  be  computed  at  run-time  rather  than  at  macro-expansion  time.  (In  the  example 
above,  (default  nil)  becomes  (default  ’nil).) 

It  may  seem  unduly  restrictive  that  defunS  does  not  support  all  of  the  standard 
keywords  in  lambda-list.  However,  this  is  not  that  much  of  a  problem  because  defmacro 
can  be  used  directly  in  situations  where  these  capabilities  are  desired.  For  example. 
Tconcatenate  is  defined  in  terms  of  a  more  primitive  oss  function  Tconcatenate2  as 
h  >liow- . 

(defmacro  Tconcatenate  (Qiterasl  0items2  ftrest  more-Oitems) 

(if  (null  more-Oitems) 

‘ (Tconcatenate2  .Oitemsl  ,0items2) 

1 (Tconcatenate2  .Oitemsl  (Tconcatenate  ,0items2  ., more-Oitems ))) ) 

I  -ing  defmacro  directly  also  make-  it  possible  to  define  low  higher order  oss  func 
tiori-.  lor  example,  an  OSS  function  analogous  to  substitute  -  if  could  be  defined  a- 
follow-.  i  [he  Eoss  ensuies  i  hat  newitera  will  only  be  evaluated  once.) 
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Cdefmacro  Osubstitute- if  (nesitem  test  items) 

(let  ((var  (gensym))) 

‘(lets  ((,var  .items)) 

(if  (funcall  .test  ,  var)  iEosc  .R  ,  r.evitem/  ,  vai)))) 

(Osubstitute- if  3  it’minusp  [l  -1  2  -3])  [l  3  2  3] 

Multiple  Values 

Ilif  oss  macro  package  supports  multiple  values  in  a  number  ot  contexts.  \-  di- 
cii'seil  above,  lets  can  be  used  to  bind  variables  to  multiple  values  returned  by  an  oss 
tunction.  (acuities  are  also  provided  lor  defining  oss  functions  which  return  multipV 
values.  The  support  for  multiple  values  is  complicated  by  the  fact  that  the  oss  macro 
package  implements  all  communication  of  values  by  using  variables.  As  a  result,  it  is  not 
possible  to  support  the  standard  <  ommon  l.isp  feature  that  multiple  values  can  coexist 
with  single  values  without  the  programmer  having  to  pay  much  attention  to  what  is  going 
on.  When  using  OSS  expressions,  the  programmer  has  to  be  explicit  about  how  many 
values  are  being  passed  around. 

•  valS  irest  expr-iist  =>  &re st  multiple-value  result 

This  is  analogous  to  values  except  that  it  can  operate  on  OSS  values.  It  takes  in 
the  values  returned  by  n  different  expressions  and  returns  them  as  n  multiple  values.  It 
enforces  the  restriction  that  the  values  must  either  all  be  OSS  values  or  all  be  non-OSS 
values.  The  following  example  shows  how  a  simple  version  of  Eplist  could  he  defined. 

(defunS  simple-Eplist  (place) 

(lets  ((plist  (Enumerate?  place  ft’cddr  K’null))) 

(valS  (car  plist)  (cadr  plist)))) 

It  is  possible  to  use  values  in  an  oss  expression.  However,  the  results  will  he  very 
different  from  the  results  obtained  Irom  using  valS.  f  he  values  will  he  implicitly  mapped 
like  any  other  non-OSS  form.  The  value  ultimately  returned  will  he  the  single  value 
returned  by  TmapF. 

(prognS  (valS  (Elist  >(l  2))  (Elist  ’(3  4))))  =>  [l  2]  [3  4] 

(prognS  (values  (Elist  ’(1  2))  (Elist  ’(3  4)))) 

E=  (prognS  (TmapF  #’ (lambda  (x  y)  (values  x  y)) 

(Elist  ’(1  2))  (Elist  ’(3  4))))  =>  [l  2] 

•  pass-valS  n  expr  =>  ftrest  multiple  -value-result 

Ibis  function  is  used  essentially  as  a  declaration.  It  tells  the  OSS  macro  package  that 
the  form  expr  returns  u  multiple  value*  which  the  programmer  wishes  to  have  preserved 
in  the  context  of  the  oss  expression.  I  Ibis  i-  needed,  because  Common  Lisp  does  not 
provide  any  compile  time  way  to  determine  the  number  ot  arguments  that  a  function  will 
return. i  1  lie  first  example  below  enumerates  a  list  of  symbols  and  returns  a  list  of  the 
internal  symbol-,  it  any.  which  torrespond  to  them.  I  he  second  example  defines  a  two 
valued  oss  function  which  locate*  symbols. 
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(lets*  ((names  (Elist  ’ (zots  Elist  zorch;)) 

((symbols  statuses)  (pass-vaiS  2  ( f :  r.d-symbol  :  string  names)))' 
(internal-symbols  (Tselect  (eq  statuses  :  internal)  symbols)); 
(Rlist  internal-symbols))  (zots  zorch) 

(defunS  find-symbols  (names) 

(declare  (type  oss  names)) 

(pass-valS  2  (find-symbol  (string  names))) 

(find-symbols  [zots  Elist  zorch] ) 

[zots  Elist  zorch]  [: internal  inherited  : internal] 

1  h<-  form  pass  -  valS  never  has  to  be  used  in  eon  in  net  ion  vv  it  ;i  an  uis  limit  ion .  !  .era  use 
the  oss  macro  package  knows  how  many  values  every  oss  function  returns.  Similarlv. 
pass-valS  never  has  to  he  used  when  multiple  values  are  being  bound  i > \  lets,  because  the 
syntax  of  t  fie  letS  indicates  how  many  values  are  return'd.  >  As  a  result,  the  pass-valS 
in  the  first  example  above  is  not  necessary.)  However,  in  situations  such  as  the  second 
example  above.  pass-valS  must  be  used. 

Alteration  of  Values 

1  he  transformations  introduced  by  theoss  macro  pac  kageare  inherently  ant  agonist  ic 
to  the  transformations  introduced  by  the  macro  setf.  In  particular,  oss  function  calls 
cannot  lie  used  as  the  destination  of  a  setf.  In  order  to  get  around  this  problem,  the-  oss 
macro  package  supports  a  separate  construct  which  is  in  fact  more  powerful  than  setf. 

•  alters  desf inaf ions  items  =>  items 

I  his  torm  takes  in  a  series  of  destinations  and  a  series  of  items  and  stores  the  items 
in  the1  destinations.  It  returns  the  series  «.f  items,  hike  setf.  alters  cannot  be  applied 
to  a  destination  unless  there  is  an  associated  definition  for  what  should  be  done  i  see  the 
discussion  of  alterableS  in  ti  ).  The  outputs  of  the  predefined  functions  Elist.  Ealist. 
Eplist.  Efringe.  Evector.  and  Esequence  are  alterable.  The  effects  of  this  alteration 
are  illustrated  in  conjunction  with  the  descriptions  of  these  functions.  For  example,  the' 
following  set-  all  of  the  elements  in  a  list  to  nil. 

(let  ((list  ’((a  .  1)  (b  .  2)  (c  .  3)))) 

(alters  (Elist  list)  nil) 
list)  =8  (nil  nil  nil) 

As  a  related  example,  consider  the  following.  Although  setf  cannot  be  applied  in 
an  oss  function,  it  can  be  applied  to  a  non  oss  function  in  an  OSS  expression.  In  the 

example  below,  setf  is  used  to  set  the  edr  of  each  'Tumuit  of  a  list  to  nil 

(let  ((list  ’((a  .  1)  (b  .  2)  (c  .  3)))) 

(prognS  (setf  (edr  (Elist  list))  nil'*) 
list)  ->  ((a)  (b)  (c)) 

\  key  feature  of  alters  is  that  tin  contrast  to  :;«t.f  1  a  structure  can  be  altered  b\ 
applying  alters  to  a  variable  who  h  contain.'  enumerated  elements  of  the  structure.  I  (its 
o  i-elul  because  t  he  old  value  iu  a  structure  can  he  used  to  ,|o  ide  what  new  value 
-mould  be  ] > u t  in  i  he  structure.  I  \\  hen  alterS  is  applied  to  such  a  variable  it  modifies 
l  lie  st  ruct  lire  being  hi  inner  a  I  e»|  loit  does  m.t  i  fiauge  the  v  a  I  in  ,  ,f  t  he  v  an  able.  I 
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(lets*  ((v  #(l  2  3)) 

(x  (Evector  v))) 

(alterS  x  (*  x  x) ) 

( valS  (Rlist  x>  v))  r  (1  2  3)  #(i  1  9,' 

Another  interesting  aspect  ot  alterS  i>  that  it  can  he  applied  to  tlie  output.'  of  a 
numher  of  transducers.  I  his  is  possible  whenever  a  transducer  passes  through  unchanged 
a  series  of  values  taken  from  an  input  which  is  itself  alterable.  Thi'  can  happen  with  ’he 
transducers  Tuntil.  TuntilF.  Tcotruncate.  Tremove-duplicates.  Tsubsenes.  Tselect. 
TselectF.  Tsplit,  and  TsplitF.  1  <  >  r  example,  the  following  takes  the  absolute  \  a  1  n  «■  of 
’  he  elements  of  a  vector. 

(lets*  ((v  #(1  -2  3)) 

(x  (TselectF  tt’minusp  (Evector  v)))) 

(alterS  x  (-  x) ) 
v)  #(1  2  3) 


Debugging 

The  OSS  macro  package  supports  a  number  of  features  which  are  intended  ’o  facilitate 
debugging.  One  example  of  this  is  the  fact  that  the  macro  package  tries  to  use  the  variable 
names  which  are  bound  by  a  lets  in  the  code  produced.  Since  the  macro  package  is  forced 
to  use  variable  renaming  in  order  to  implement  variable  scoping,  it  cannot  guarantee  that 
these  variable  names  will  be  used.  However,  there  is  a  high  probability  that  they  will. 
If  a  break  occurs  in  the  middle  of  an  OSS  expression,  these  variables  can  be  inspected 
in  order  to  determine  what  i>  going  on.  If  a  lets  variable  holds  an  OSS  series,  then  the 
variable  will  contain  the  current  element  of  the  series.  For  example,  the  OSS  expression 
below  is  transformed  into  the  loop  shown.  (For  a  discussion  of  how  this  transformation 
is  performed  see  6.1 

(letS*  ((v  (get-vector  user)) 

(x  (Evector  v) ) ) 

(Rsum  x)) 

(let  (#:index-9  tt:last-8  #:smn-2  x  v) 

(setq  v  (get-vector  user)) 

(tagbody  (setq  #:mdex-9  -1) 

(setq  #:last-8  (length  v)) 

(setq  #:sum-2  0) 

# : L - 1  (incf  #:index-9) 

(if  (not  (<  #:index-9  #:last-8))  (go  oss:END)) 

(setq  x  (aref  v  #:index-9)) 

(setq  #:sum-2  (+  #:sum-2  x)) 

(go  # : L- 1 J 

oss : EMD) 

K : sum-2) 

showS  t  hiiifl  ^optional  ( format  "*7,*S")  (stream  *standard-output*)  =>  thing 

I  his  function  is  convenient  ‘or  printing  out  debugging  information  while  an  oss  ex 
pression  i>  being  evaluated.  It  can  be  wrapped  around  any  expression  no  matter  whether 


Reference  M.tinntl 


it  produces  an  oss  value  or  a  non  OSS  value  without  disturbing  (he  containing  expression. 
1  he  function  prints  out  the  value  and  then  returns  it.  If  the  value  is  a  non-OSS  thing, 
it  will  he  printed  out  once  at  the  time  it  is  created.  It  it  is  an  OSS  series  thing;,  it  will 
he  printed  out  an  element  at  a  time.  The  turinat  can  he  used  to  print  a  tag  in  order  to 
identify  the  value  being;  shown. 

(shosS  format  stream) 

EE  (let  ( ( x  thing))  (format  stream  format  x)  x) 

(lets  ((x  (Elist  ’(1  2  3)))) 

(Rsum  (shosS  x  "Item:  'A,  ")))  =>  6 

;  ;The  output  "Item:  1,  Item:  2,  Item:  3,  "  is  printed. 

•  ‘permit -non- terminating -oss -express  ions* 

On  the  theory  that  non-terminating  loops  are  seldom  desired,  the  OSS  macro  package 
checks  each  loop  constructed  to  see  if  it  can  terminate.  If  this  variable  is  nil  (which  0 
the  default ).  then  an  error  message  is  issued  for  each  loop  which  the  OSS  macro  package 
thinks  has  no  possibility  of  terminating.  This  is  useful  in  the  first  example  below  but 
not  in  the  second.  The  form  compiler-let  can  be  used  to  bind  this  variable  to  T  around 
such  an  expression. 

(Rlist  4)  ;Signals  error  15 

(block  bar  ; Signals  error  15 

(letS  ((x  (Eup  : by  10))) 

(if  (>  x  15)  (return-from  bar  x)))) 

(compiler-let  ((*permit-non-terminating-oss-expressions*  T)) 

(block  bar 

(letS  ((x  (Eup  : by  10))) 

(if  (>  x  15)  (return-from  bar  x)))))  20 

•  *last-oss-loop* 

I  his  variable  contains  the  loop  most  recently  produced  by  the  OSS  macro  package. 
Alter  evaluating  (or  macro-expanding)  an  OSS  expression,  this  variable  can  be  inspected 
in  order  to  see  the  code  which  was  produced. 

•  *last-oss-error* 

1  his  variable  contains  the  most  recently  printed  error  message  produced  by  the  oss 
macro  package.  The  information  in  this  variable  can  be  useful  for  tracking  down  errors. 

Side-Effects 

The  oss  macro  package  works  by  converting  each  oss  expression  into  a  loop.  I  his 
allows  the  expressions  to  be  evaluated  very  eflieient ly.  but  radically  changes  the  order 
in  which  computations  are  performed.  In  addition,  off-line  ports  are  .supported  by  code 
motion,  (liven  ail  of  these  changes,  it  is  not  surprising  that  oss  expressions  are  primarily 
intended  to  be  used  in  situations  where  there  are  no  side  effects.  Due  to  the  change  in 
computation  order,  it  ran  be  hard  to  figure  out  what  the  result  of  a  side  effect  will  be 
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Xevert heless.  since  si d *'  «-tt t ■<•  t ^  (particularly  in  the  form  of  input  and  output)  are  an 
inevitable  part  of  programming,  several  steps  are  taken  in  order  to  make  the  behavior  of 
oss  expressions  containing  side  effect  operation-  a-  easv  to  understand  a-  possible.  First, 
when  implicit  mapping  is  applied,  it  is  applied  to  as  large  a  subexpression  as  possible. 
This  makes  it  straightforward  to  understand  the  interaction  of  the  side-effects  within  a 
single  mapped  subexpression.  Several  examples  of  this  are  given  in  the  section  above 
which  discusses  implicit  mapping. 

Second,  wherever  possible,  the  OSS  macro  package  leaves  the  order  of  evaluation  of 
the  OSS  functions  in  an  expression  unchanged.  Kadi  function  is  evaluated  incrementally 
an  element  at  a  time,  but  on  each  cycle,  the  processing  follows  the  syntactic  ordering  of 
the  functions  in  the  expression. 

The  one  place  where  order  changes  are  required  is  when  handling  ofl-line  ports.  How¬ 
ever,  tilings  are  simplified  here  by  ensuring  lhat  the  evaluation  order  implied  by  the  order 
of  the  inputs  of  an  off-line  function  is  preserved. 

Third,  when  determining  whether  or  not  each  termination  point  is  connected  to  every 
output  in  each  on-line  subexpression,  functions  whose  outputs  are  not  used  lor  anything 
are  considered  to  be  outputs  of  the  subexpression.  The  reasoning  behind  this  is  that  if 
the  outputs  are  not  used  for  anything,  then  the  function  must  be  being  used  for  side-effect 
and  it  must  matter  tha*  the  function  get  evaluated  the  full  number  of  time-  it  should  be. 
For  example,  consider  the  expressions  below.  The  first  expression  prints  out  the  numbers 
in  a  list  and  returns  the  first  negative  number.  The  second  expression  signals  an  error.  If 
it  did  not  signal  an  error,  it  would  fail  to  print  out  all  of  the  numbers  in  the  list,  because 
Rfirst  was  cause  the  expression  to  terminate  prematurely. 

(lets*  ((x  (Elist  ’(1  23-4  5)))) 

(princ  x) 

(Rf irst-passive  (TselectF  #’rainusp  x)))  -g*  -4 

;;The  output  "123-45"  printed. 

(lets*  ((x  (Elist  ’(1  23-4  5))))  ;Signals  error  18 

(princ  x) 

(Rfirst  (TselectF  #’minusp  x))) 
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4.  Error  Messages 
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In  order  to  facilitate  the  debugging  oi  oss  expressions,  this  section  discusses  the 
various  error  messages  which  can  lie  issued  by  the  OSS  macro  package  when  processing 
the  functions  described  in  this  document.  Each  of  these  error  messages  is  printed  out  in 
the  following  format.  (This  format  is  shown  as  it  appears  on  the  Symbolics  Lisp  machine 
and  may  differ  in  minor  ways  in  other  systems.) 

Warning:  Error  error-number  in  OSS  expression: 

containing  OSS  expression 
der ai/ed  error  message 

For  example,  the  following  error  message  might  be  printed. 

Warning:  Error  1.1  in  OSS  expression: 

(LETS  ((X  (ELIST  NUMBER-LIST)) 

(Y  (EUP  (CAR  HEADER)  :T0  4  : LENGTH  5))) 

(RLIST  (LIST  Y  X))) 

Too  many  keywords  specified  in  a  call  on  Eup: 

(EUP  (CAR  HEADER)  :T0  4  : LENGTH  5) 


The  first  line  of  each  error  message  specifies  the  number  of  the  error.  This  number 
is  useful  for  looking  up  documentation  for  the  error  below.  The  next  part  of  the  error 
message  shows  the  complete  OSS  expression  which  contains  the  error.  This  makes  it  easier 
to  locate  the  error  in  a  program.  The  remainder  of  the  message  describes  the  particular 
error  in  detail.  (The  variable  *last-oss~«rror*  contains  a  list  of  the  information  svhich 
was  used  to  print  out  the  most  recent  error  found  by  the  OSS  macro  package.) 

The  OSS  macro  package  reports  errors  using  warn  so  that  processing  of  other  parts 
of  a  program  can  continue,  potentially  finding  other  errors.  However,  each  time  an  OSS 
error  is  detected,  the  OSS  macro  package  skips  over  the  rest  of  the  OSS  expression  without 
performing  any  addition  checks.  Therefore,  even  if  there  are  several  OSS  errors  in  an  OSS 
'■xpression,  only  one  OSS  error  will  be  reported.  When  an  OSS  error  is  found,  a  dummy 
value  is  inserted  in  place  of  the  erroneous  OSS  expression.  As  a  result,  it  is  virtually 
impossible  for  the  containing  program  to  run  correctly. 

A  key  feature  of  the  oss  error  messages  is  that  they  attempt  to  provide  large  amounts 
of  contextual  information  by  printing  out  portions  of  program  text.  Given  that  OSS 
expressions  go  through  multiple  stages  of  macro  processing,  the  macro  package  has  to 
work  quite  hard  in  order  to  try  to  ensure  that  the  program  text  printed  corresponds  to 
actual  ii'cr  input,  rather  than  some  intermediate  stage  of  the  processing.  The  package 
G  quite  successful  in  doing  this,  however,  in  certain  obscure  situations,  it  can  fail.  In 
particular,  n  i"  -ometimes  unable  to  locate  any  user  text  to  print  out.  When  this  happens, 
a  "?"  is  printed  in  lieu  of  a  piece  ot  program  text. 

The  documentation  below  describes  each  of  the  error  messages  which  the  OSS  macro 
package  can  produce.  Each  description  begins  with  a  header  line  containing  a  schematic 
rendition  of  an  error  message.  Italics  is  used  to  indicate  pieces  of  specific  information 
which  is  inserted  in  the  message.  The  number  of  the  error  is  shown  in  the  left  margin  at 


the  beginning  of  the  header.  For  ease  ot  reference,  the  errors  are  described  in  numerical 
order. 

Local  errors  concerning  single  OSS  functions.  The  following  error  messages 
report  errors  which  are  local  in  that  they  stem  purely  from  the  improper  use  of  a  single 
OSS  function.  These  errors  cover  only  a  few  special  situations.  Many  (if  not  most  )  local 
errors  are  reported  directly  by  the  standard  Common  Lisp  processor  rather  than  by  the 
OSS  macro  package.  For  example,  if  an  OSS  function  is  used  with  the  wrong  number  of 
arguments,  an  error  message  is  issued  by  the  standard  macro  expander. 

1.1  Too  many  keywords  specified  in  call  on  Eup:  call 

1.2  Too  many  keywords  specified  in  call  on  Edown:  call 

1.3  Too  many  keywords  specified  in  call  on  Hatch:  call 

Each  of  these  errors  specifies  that  incompatible  keywords  have  been  provided  for  the 
indicated  function.  The  entire  function  call  is  printed  out  as  shown  above. 

2  Invalid  enumerator  arg  to  TconcatenateF :  enumerator 

This  error  is  issued  if  the  enumerator  argument  to  TconcatenateF  fails  to  be  an 
enumerator — i.e.,  fails  to  be  an  OSS  function  that  has  no  OSS  inputs,  at  least  one  OSS 
output,  and  which  can  terminate. 

3  Unsupported  A-keyword  keyword  in  defunS  arglist. 

This  error  is  issued  if  an  ft-keyword  other  than  Aoptional  or  ftkey  appears  in  the 
argument  list  of  defunS.  Other  keywords  have  to  be  supported  by  using  defmacro  directly. 
(See  the  discussion  of  defunS.) 

1  AlterS  applied  to  an  unalterable  form:  call 

This  error  is  issued  if  alters  is  applied  to  a  value  which  is  not  alterable.  Values  are 
alterable  only  if  they  come  directly  front  an  enumerator  which  has  an  alterable  value, 
or  come  indirectly  from  such  an  enumerator  via  one  or  more  transducers  which  allow 
aiterability  to  pass  through. 

b  Malformed  lambdas  argument  arg. 

I  his  error  message  is  issued  if  an  argument  of  a  lambdaS  fails  to  be  a  valid  variable. 
In  particular,  it  is  issued  if  the  argument,  is  not  a  symbol,  is  T  or  nil.  is  a  symbol  in 
the  keyword  package,  or  is  an  Jk-keyword.  (It  is  also  erroneous  for  such  a  variable  to  be 
declared  special.  However,  this  error  is  only  reported  on  the  Symbolics  Lisp  Machine.) 

fi.  1  Lambdas  used  in  inappropriate  context:  call 

1  his  error  message  is  issued  if  a  lambdas  ends  up  (after  macro  expansion  of  the 
surrounding  code)  being  used  in  any  context  other  than  as  the  quoted  first  argument  of 
a  funcallS. 

7  Wrong  number  of  args  to  funcallS:  call 

I  his  error  message  is  issued  if  a  use  of  funcallS  does  not  contain  a  number  of  argu¬ 
ments  which  is  compatible  with  the  number  of  arguments  expected  by  the  OSS  functional 
argument. 


s  Only  n  return  values  present  where  m  expected:  call 

1  hi-  error  mosii^r  is  issued  il  an  oss  function  is  used  in  a  situation  where  it  is 
expected  to  return  more  value,',  than  it  actually  does  for  example,  it  a  lets  tries  to  hind 
two  values  from  an  oss  function  width  only  returns  one.  or  pass-valS  tries  to  obtain  two 
values  from  an  oss  function  which  only  returns  one.  i \oii-OSS  functions  return  extra 
values  of  nil  if  they  are  requested  to  produce  more  values  than  they  actually  do.' 

Errors  concerning  OSS  variables.  1  he  following  errors  concern  the  creation  and 
Use  of  lets  and  lambdas  variable:-,  hike  tlx*  ones  above,  they  are  quite  local  in  nature 
and  relatively  easy  to  fix. 

ft  Malformed  letS{*[  binding  pair  pair. 

This  error  message  is  issued  if  a  letS  or  lets*  binding  pair  fails  to  be  either  a  list  of 
a  valid  variable  and  a  value,  or  a  list  of  a  list  of  valid  variables  and  a  value.  1  he  criterion 
for  what  makes  a  variable  valid  is  the  same  as  the  one  used  in  Error  T.  except  that  a 
binding  pair  can  contain  nil  instead  of  a  variable. 

10  The  variable  var  erroneously  declared  TYPE  OSS  in  a  letS{*}. 

This  message  is  issued  if  a  variable  in  a  lets  is  explicitly  declared  to  be  of  type  oss. 

11  The  letS{*}  variable  variable  is  unused  in:  call 

This  error  message  is  issued  if  a  variable  in  a  lets  is  never  referenced  in  the  body 
of  the  lets.  Note  that  these  variables  cannot  be  referenced  inside  a  nested  lambda  or 
lambdaS. 

12  The  letSf*}  variable  var  setqed. 

This  error  message  is  issued  if  a  lets  variable  (either  OSS  or  non-OSS  I  is  assigned  to 
in  the  body  of  a  lets.  ft  is  also  issued  if  any  of  the  variables  bound  by  a  lambdaS  or 
defunS  are  assigned  to. 

Non-local  errors  concerning  complete  OSS  expressions.  The  following  errors 

concern  non-local  problems  in  Oss  expressions.  The  first  two  are  discussed  in  further 
detail  in  the  -ection  on  implicit  mapping. 

12  Decomposition  moves:  code  out  of  a  binding  scope:  surround 

This  error  is  issued  if  the  processing  preparatory  to  implicit  mapping  causes  a  subex¬ 
pression  to  be  moved  out  of  the  binding  scope  for  one  of  the  variables  in  it.  The  error 
can  be  lixed  by  using  lets  to  create  the  binding  scope,  or  by  moving  the  binding  form 
-o  that  it  surrounds  the  entire  oss  expression.  (The  testing  for  this  error  is  somewhat 
approximate  in  nature.  It  can  tni--  some  erroneous  situations  and  can  complain  in  some 
situation-  where  there  is  no  problem.  In  these  latter  situations,  variable  renaming  can 
be  used  to  eliminate  the  complaint.) 

I  1  OSS  value  carried  to  non-OSS  input  by  data  flow  from:  call  to:  rail 

As  illustrated  below,  tins  error  is  issued  whenever  data  flow'  connects  an  OSS  output 
to  a  non  OSS  input  of  an  oss  function  as  in  the  example  below.  (If  the  expression  in 
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question  is  intended  to  contain  a  lasted  loop,  the  error  can  he  fixed  by  wrapping  tin- 
nested  portion  in  a  mapS.) 

Warning:  Error  14  in  OSS  expression: 

(Rlist  (Rlist  (Elist  (Elist  ’((l  2)  (3  4)))))) 

OSS  value  carried  to  non-OSS  input  by  data  flow  from: 

(Elist  ’((1  2)  (3  4))) 
to : 

(Elist  (Elist  ’((1  2)  (3  4)))) 

The  error  message  print s  out  two  pieces  of  code  in  order  to  indicate  the  source  and 
destination  of  the  erroneous  data  flow.  The  outermost  part  of  the  first  piece  of  code 
shows  the  function  which  creates  the  value  in  question.  The  outermost  function  in  the 
second  piece  of  code  shows  the  function  which  receives  the  value.  (  Entire  subexpressions 
are  printed  in  order  to  make  it  easier  to  locate  the  functions  in  question  within  the  oss 
expression  as  a  whole.)  If  nesting  of  expressions  is  used  to  implement  t  he  data  How.  then 
the  first  piece  of  code  will  be  nested  in  the  second  one. 

15  Non-terminating  OSS  expression:  expr 

This  error  message  is  issued  whenever  a  complete  OSS  expression  appears  incapable  of 
terminating.  The  expression  in  question  is  printed.  It  may  well  be  only  a  subexpression 
of  the  OSS  expression  being  processed.  (This  error  message  can  be  turned  off  by  using 
the  variable  *permit-non-terminating-oss-expressions*.) 

Errors  concerning  the  violation  of  restrictions.  These  errors  are  issued  when 
an  OSS  expression  violates  one  of  th>-  isolation  restrictions  or  the  requirement  that  within 
each  on-line  subexpression,  there  must  be  a  data  flow  path  from  each  termination  point 
to  each  out  put . 

16  Non- isolated  non-oss  data  flow  from:  rail  to:  rail 

This  error  is  issued  if  an  OSS  expression  violates  the  non-OSS  data  flow  isolation 
restriction.  As  shown  below,  the  error  message  prints  out  two  pieces  of  code  which 
indicate  the  data  flow  which  triggered  the  error. 

Warning:  Error  16  in  OSS  expression: 

(LETS*  ( (NUMS  (EVECTOR  #(3  2  8))) 

(TOTAL  (REDUCEF  0  #’+  NUMS))) 

(RVECTOR  (/  NUMS  TOTAL))) 

Non-isolated  non-OSS  data  flow  from: 

(REDUCEF  0  #’+  NUMS) 
to : 

(/  NUMS  TOTAL) 

As  discussed  on  page  10.  errors  of  this  type  can  always  be  eliminated  by  duplicating 
subexpressions  until  the  data  flow  in  question  becomes  isolated,  l  or  example,  the  error 
above  could  be  fixed  by  duplicating  t lie  expression  (Evector  #(3  2  8)). 

17.1  Non-isolated  oss  input  at  the  end  of  the  data  flow  from:  rail  to:  rail 

17.2  Non-isolated  oss  output  at  the  start  of  the  data  flow  from:  rail  to:  rail 

One  of  these  errors  is  issued  if  an  OSS  expression  violates  the  oft  line  port  isolation 
restriction.  I  he  error  message  prints  out  two  pieces  of  code  which  indicate  a  data  flow 


'a  hi  i'll  ends  inr  'tart'  i  on  tin-  port  m  quest  mn.  A'  discussed  o  n  page  10.  errors  of  till' 
type  .an  always  be  eliminated  l.\  c , ;;  |.l  j.-.it  i  ng  subexpressions  until  the  i»ort  in  question 

1  a * 1 1 a1 '  i  -  i »! a t t‘i  1 

l"'  No  data  flow  path  from  the  termination  point:  rail  to  the  output:  call 

I  hi'  error  i'  issued  it  a  termination  point  in  an  on-line  subexpression  ot  an  oss 
expression  i'  not  .a  m  him  ted  by  data  tl*  > \v  t  o  one  of  t  he  out  put  s.  As  discussed  on  pane  1J. 
t  fie  error  can  op  en  be  fi  xed  !  >v  iioug  non  -  early  terniinat  inn  OSS  function.'  inst  ead  of  ea  rly 
terminating  lutu  :  ions.  In  ot  In--  'it  iia  t  i < > 1 1 .  1 1. e  error  can  be  fi  xed  by  tisi ng  Tcotruncate 
to  indicate  r*d -•  t io ri > h i P'  between  ups  \t  tin  ivnot .  code  copying  can  be  used. 

Errors  concerning  implementation  limitations.  These  errors  reflect  limitation." 
of  the  way  t  fie  oss  macro  package  o  implemented  rather  than  anything  fundamental 
about  ( >ss  expression". 

1 ' )  LambdaS  body  too  complex  to  merge  into  a  single  unit:  forms 

In  general,  the  oss  macro  package  is  capable  of  cotnbinitig  together  any  kind  of  per 
missible  oss  expression.  In  particular.  there  is  never  a  problem  as  long  as  tin*  expression 
as  a  whole  does  not  have  any  oss  inputs  or  oss  outputs.  However,  in  tile  body  of  a 
lambdas,  it  is  possible  to  write  oss  expressions  which  have  both  OSS  input'  and  oss 
outputs.  If  such  ari  expression  has  a  data  flow  path  from  an  OSS  input  to  an  oss  output 
which  contains  a  non-oss  data  flow  arc.  then  this  error  message  is  issued.  Tor  example, 
t  lie  error  would  be  issued  in  the  situation  below. 

(funcallS  #’ (lambdas  (items)  ;Signals  error  19 

(declare  (type  oss  items)) 

(Elist  (Rlist  items))) 

...  ) 

An  error  message  is  issued  in  t lie  situation  above,  because  the  situation  is  unlikely 
to  occur  and  there  is  no  way  to  support  t lie  situation  without  resorting  to  very  peculiar 
code.  In  particular,  the  input  items  in  the  example  above  would  have  to  lie  converted 
into  an  off  line  input . 

.’ll  The  form  hmc'i"n  not  alloved  in  OSS  expressions. 

In  general,  the  oss  macro  package  has  a  sufficient  understanding  of  special  forms  to 
handle  them  correctly  when  they  appear  in  an  oss  expression.  However,  it  does  not 
handle  the  forms  compiler-let.  flet.  labels,  or  macrolet.  I  he  forms  compiler-let  and 
macrolet  would  not  be  that  hard  ro  handle,  however  it  does  not  seem  worth  the  effort, 
[he  Ion  a-  flet  and  labels  would  be  hard  to  handle,  because  the  oss  macro  package 
dee-  not  preserve  binibng  s>  opes  and  therefore  does  not  have  any  obvious  place  to  put 
'f  ’-m  in  t he  code  it  produce'.  All  four  form?  can  be  used  by  simply  wrapping  them 
around  entire  oss  expressions  rather  than  putting  them  in  the  expressions. 

* 

7  I  tocu  me;it  at  ion  tor  these  errors  appears  hi  ti  . 
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5.  Index  of  Functions 


t  his  section  is  an  index  and  concise  summary  of  the  functions,  variables,  and  special 
forms  described  in  this  document.  Each  entry  shows  the  inputs  and  outputs  of  the 
function,  the  page  where  documentation  can  lie  found,  and  a  one  line  description. 

The  names  of  OSS  functions  often  start  with  one  of  the  following  prefix  letters. 

E  Enumerator. 

T  Transducer. 

E  Reducer. 

Occasionally,  a  name  will  end  with  one  of  the  following  suffix  letters. 

S  Special  form. 

F  Function  that  takes  functional  arguments. 

In  addition,  the  argument  and  result  names  indicate  data  type  restrictions  le.g.. 
number  indicates  that  an  argument  must  be  a  number,  item  indicates  that  there  is  no 
yvpe  restriction).  Plural  names  are  used  iff  the  value  in  question  is  an  OSS  series  (e.g.. 
numbers  indicates  an  OSS  series  of  numbers:  items  indicates  an  OSS  series  of  unrestricted 
values).  The  name  of  a  series  input  or  output  begins  with  “0"  iff  it  is  off-line. 

alters  destinations  items  =>  item s 

p.  18  Alters  the  values  in  destinations  to  be  items. 
defunS  unine  lambda-list  {doe}  {deelj*  Abody  expr  list 
[>.  Mi  Defines  an  OSS  function,  see  lambdas. 

Ealist  a/isf  Aoptional  (test  A’eql)  =>  keys  values 

p.  17  Creates  two  series  containing  the  keys  and  values  in  an  alist. 

Edown  Aoptional  (start  0)  Akey  (:by  1)  :  to  :  above  :  length  numbers 
p.  16  Creates  a  series  of  numbers  by  counting  down  from  start  by  :by. 

Efile  name  =>  items 

p.  20  Creates  a  series  of  the  forms  in  the  file  named  name. 

Efringe  free  Aoptional  (leaf-test  #’atom)  =>  leaves 
p.  1  s  Creates  a  series  of  the  leaves  of  a  tree. 

Ehash  table  =>  keys  values 

[).  10  Creates  two  series  containing  the  keys  and  values  in  a  hash  table. 

Elist  list  Aoptional  (end-test  tt’endp)  =>  elements 
p.  16  Creates  a  series  of  t he  element s  in  a  list. 

EnumerateF  iuit  step  Aoptional  test  ->  items 

[).  20  Creates  a  series  by  applying  step  to  iuit  until  test  returns  non-null. 

Enumerate- inclusiveF  iuit  step  test  >  items 

p.  20  Creates  a  series  containing  one  more  element  than  EnumerateF. 

Eoss  Arest  expr  list  =>  items 

p.  lb  Creates  a  series  of  the  results  of  the  expressions. 

Eplist  pi  is  t  =>  indicators  values 

p  17  Creates  two  senes  containing  the  indicators  and  values  in  a  plist. 
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Esequence  -etpience  toptional  v  uido  r-  (Eup))  elements 
p.  I!t  (  r.-aic-  a  <t'r’(s  ot  the  element  s  m  a  sequence. 

Esuhlists  b.-t  Aeptional  ( r ■  1 1 •  /  r.--r  #’endp)  y-  -i ibli-ts 
p.  1  *  i  (  rcaii'>  <i  ol  'hr  ~  >  1 1  *  1  i  -•  t  s  in  a  li-l. 

Esymbols  ^optional  (package  ‘package* )  =>  symbols 
p.  1*  Creates  a  >i‘ri‘s  ,it  the  symbols  m  package. 

Etree  f ree  toptional  (Cat-fesf  tt’atoin)  / unit's 

p.  I''  Creates  a  senes  she  in  des  in  a  Ire*-. 

Eup  ftopt tonal  (-t.irt  0)  ftkey  (:by  l)  :to  :  below  :  length  =P  numbers 
p.  15  Create.  <i  senes  til  numbers  by  counting  up  from  '•t.irt  by  :by. 

Evector  v».vf or  toptional  ( in-lice -  (Eup))  elements 
|).  1  S  Creates  a  series  ol  the  iv'im'ntj  in  a  vector. 
funcallS  Inaction  irest  expr-list  >  result 

p.  15  Applies  an  oss  function  to  'lie  results  ol  the  expressions, 
lambdas  var/isf  {dec!}*  ibody  expr-list 

p.  1  1  form  fur  spec:  lying  literal  oss  lunctions. 

♦las t-oss- error* 

[).  -50  Variable  containing  a  description  of  the  last  error  in  an  OSS  expression, 
♦last-oss-loop* 

p.  50  Variable  containing  the  loop  the  last  OSS  expression  was  converted  into, 
lets  var-valne- pair-list  {dec/}*  ftbody  expr-list  =>  result 
p.  d7  Binds  OSS  variables  in  parallel, 
lets*  var- value-pair-list  {dec/}*  ftbody  expr-list  =>  result 
p.  d9  Binds  OSS  variables  sequentially. 
mapS  ftbody  expr-list  =>  items 

p.  1-5  C  auses  expr-list  to  tie  mapped  over  the  oss  variables  in  it. 
oss-tutorial-mode  ^optional  (  /-or  ni/T)  state-of- tutorial-mode 
p.  14  If  called  with  an  argument  of  T.  turns  tutorial  mode  on. 
pass-valS  n  expr  =>  ftrest  mnltiple-value-resnlt 

[).  47  1  sed  to  pass  multiple  value-;  from  a  non-OSS  function  into  an  OSS  expression, 
♦permit -non- terminating-oss -expressions* 

p.  50  When  non-null,  inhibits  error  messages  about  non-terminating  OSS  expressions. 
prognS  ibody  expr-list  =>  result 

p.  d0  Delineates  an  OSS  expression. 

Ralist  keys  values  =>  a  list 

p.  d'J  Combines  a  series  of  keys  and  a  series  of  values  together  into  an  alist. 

Rand  bools  =>  bool 

p.  dti  Computes  the  and  of  the  elements  of  bools,  terminating  early. 

Rand- late  bools  =>  bool 

p.  do  Computes  the  and  of  the  elements  of  bools. 

Rappend  lists  list 

p.  -V2  Appends  the  elements  * >1  li-ts  together  into  a  single  list. 

Rbag  items  list 

p.  d.!  Combines  the  elements  o|  item-  together  into  an  unordered  list. 
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ReduceF  init  function  items  =>  result 

p.  35  Computes  a  cumulative  value  by  applying  function  to  the  elements  of  items. 
Rfile  name  items  Arest  option-plist  =>  T 

p.  31  Prints  the  elements  of  items  into  a  file. 

Rfirst  items  ^optional  ( default  nil)  =>  item 

p.  35  Returns  the  first  element  of  items,  terminating  early. 

Rfirst-late  items  Aoptional  ( default  nil)  =>  item 
p.  35  Returns  the  first  element  of  items. 

Rhash  keys  values  Arest  option-plist  table 

p.  33  Combines  a  series  of  keys  and  a  series  of  values  together  into  a  hash  table. 
Rlast  items  Aoptional  ( default  nil)  =>  item 
p.  34  Returns  the  last  element  of  items. 

Rlength  items  =>  number 

p.  34  Returns  the  number  of  elements  in  items. 

Rlist  items  list 

p.  32  Combines  the  elements  of  items  together  into  a  list. 

Rraax  numbers  =>  number 

p.  34  Returns  the  maximum  element  of  numbers. 

Rmin  numbers  =>  number 

p.  34  Returns  the  minimum  element  of  numbers. 

Rnconc  lists  =>  list 

p.  32  Destructively  appends  the  elements  of  lists  together  into  a  single  list. 

Rnth  n  items  Aoptional  (default  nil)  =>  item 

p.  35  Returns  the  nth  element  of  items,  terminating  early. 

Rnth-late  n  items  Aoptional  ( default  nil)  item 
p.  35  Returns  the  /it h  element  of  items. 

Ror  bools  =>  bool 

p.  36  Computes  the  or  of  the  elements  of  bools,  terminating  early. 

Ror-late  bools  =>  bool 

p.  3fi  Computes  the  or  of  the  elements  of  bools. 

Rplist  indicators  values  =>  plist 

p.  33  Combines  a  series  of  indicators  and  a  series  of  values  together  into  a  plist. 
Rsum  numbers  number 

p.  34  Computes  the  sum  of  the  elements  in  numbers. 

Rvector  items  Akey  (.size  32)  Arest  option-plist  =>  vector 

p.  33  Combines  the  elements  of  items  together  into  a  vector. 
showS  thing  Aoptional  (format  '"7,'S")  (stream  *standard-output*)  =>  tiling 
j).  1't  Displays  thing  for  debugging  purposes. 

Tchunk  amount  Oitems  =>  lists 

p.  27  Creates  a  series  of  list.'  of  length  amount  of  non  overlapping  subseries  of  Oitem 
Tconcatenate  Oitemsl  Oitems-  Arest  more-Oitems  =>  items 
p.  27  Concatenates  two  or  more  series  end  to  end. 

TconcatenateF  /'  numerator  Oitems  =>  items 

p.  27  Concatenates  the  results  of  applying  Enumerator  to  the  elements  of  Oitems. 
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Tcotruncate  items  trest  more-items  =>  initial-items  trest  more-initiai-itenis 
p.  25  Truncates  all  the  inputs  to  the  length  of  the  shortest  input. 

Texpand  bools  Oitems  toptional  (default  nil)  items 

p.  30  Spreads  the  elements  ot  items  out  into  the  indicated  positions. 

Tlastp  Oitems  =?>  bools  items 

p.  29  Determines  which  element  of  the  input  is  the  last. 

Hatch  items  tkey  :after  :before  :pre  :post  =>  masked-items 
p.  21  Modifies  a  series  before  or  after  a  latch  point. 

TmapF  function  trest  items-list  =>•  items 

p.  23  Map  function  over  the  input  series. 

Tmask  Omonotonic-indices  =>  bools 

p.  28  Creates  a  series  continuing  T  in  the  indicated  positions. 

Tmerge  Oitemsl  Oitems2  comparator  =>  items 
p.  28  Merges  two  series  into  one. 

Tpositions  Obools  =>  indices 

p.  28  Returns  a  series  of  the  positions  of  non-null  elements  in  Obools. 

Tprevious  items  toptional  (default  nil)  ( amount  1)  =>  shifted-items 
p.  21  Shifts  items  to  the  right  by  amount  inserting  default. 

Tremove-duplicates  Oitems  toptional  (comparator  #’  eql)  =>  items 
p.  26  Removes  the  duplicate  elements  from  a  series. 

TscanF  {init}  function  items  =>  results 

p.  23  Computes  cumulative  values  by  applying  function  to  the  elements  of  items. 
Tselect  bools  toptional  items  =>  Oitems 

p.  29  Selects  the  elements  of  items  corresponding  to  non-null  elements  of  bools. 
TselectF  pred  items  =>  Oitems 

[).  30  Selects  the  element'  of  items  for  which  pred  is  non-null. 

Tsplit  items  bools  trest  more-bools  =>  Oitemsl  Oitems'2  trest  more-Oitems 
p.  31  Divides  a  series  into  multiple  outputs  based  on  bools. 

TsplitF  items  pred  trest  more-pred  =>  Oitemsl  Oitems'2  trest  more  Oitems 
p.  31  Divides  a  series  into  multiple  outputs  based  on  pred 
Tsubseries  Oitems  start  toptional  (below  (length  Oitems ))  =>  items 

p.  27  Returns  the  elements  of  Oitems  from  start  up  to.  but  not  including,  below. 
Tuntil  bools  items  =>  initial-items 

p.  22  Returns  items  up  to.  but  not  including,  the  first  non  null  element  of  bools. 
TuntilF  pred  items  =>  initial-items 

p.  22  Returns  items  up  to.  but  not  including,  'he  first  element  which  satisfies  pred. 
Twindos  amount  Oitems  =>  lists 

p.  27  Creates  a  serie>  ot  lot'  of  length  amount  of  'ucce"i\e  overlapping  subseries, 
type  oss  trest  variable-list 

p.  15  Declaration  used  to  'peeify  that  variable'  are  oss  variables. 
valS  trest  expr-list  =>  t rest  multiple  value  result 
p.  47  Returns  multiple  serie'  value'. 


